Hey Kids…Wanna Job as a Developer…Start Developing

I’ve scoured many resumes of young, hopeful software developers, and have interviewed and spoke to a fair number as they exit college and are trying to embark on a career in the software development world.  As I think through what separates the interesting candidates from the non-interesting candidates, one of the main items is simply: is he or she presently writing code?

I once was speaking to a newspaper journalist friend and he said something that has resonated with me since.  He basically said, “I speak with all kinds of kids who have been out of school for 6 months, or a year, or more and are having trouble getting a paid gig.  They all seem to have the requisite skills from college: school newspaper, school web-page copy, etc.  All of that is fine and necessary, but what separates the ones that you would hire from those that you wouldn’t is simple: are you writing?  If you want to be a writer, then you’ll be writing, whether or not you are being paid for it.  It costs literally nothing to be writing. Have a blog, submit free-lance stuff, create some sort of e-newsletter…something!”

This resonated with me because in this particular case, software development is very much like writing.  The barrier to entry is quite small, or even zero.  You should already have the tools, or can get the tools for little investment, so there is no excuse why you aren’t already doing it, regardless of whether or not you are being paid.

If you are interested in developing software, then nothing conveys that better than simply doing it on your own.  It shows initiative, it shows you are in fact actually interested in developing software, it shows you can put your mind to something and make progress….all of these are the kinds of qualities for which employers will be looking.

You see, there is often little to separate you from the pack as you exit college.  That’s not entirely your fault, but for sure the people that have “done something” in addition to, or along with their studies do stick out.  During the interview process, your prospective employer is likely not only to be asking questions about your grades, your classes, and your knowledge (blah, blah, blah…), but about who you are, what your interests are, what makes you tick, and how that may fit into the organization and how you will contribute.  In my opinion (I’m sure many others disagree), where you went to school and your GPA are almost useless.  What I care about is how you will contribute, and how you will grow.  Neither of these comes out of school name or grades (OK…maybe a little…but really…I don’t care).  A team member is most productive when they care about what they are doing…when they are learning…when they find it interesting..when they like and work well with the other team members.  Again…no grades in that list.

So what to do?  Do this…

• Join an Open Source Project
• Buy a Raspberry Pi and make something
• Make an iOS or Android app
• Make some sort of web-based something to do…something…anything
• At the very least (the…very…least) go through tutorials (Python, C, Java, PHP, etc) on various languages and develop some simple programs (although this really should be in the context of the above points)

It doesn’t really matter if you have a good app or product idea or not.  Your potential employer is not judging you on your idea.  What matters is you have a goal and you are working toward it and teaching yourself to be a developer in the process.

As you are exiting college, you’re not really expected to be an expert software architect, or master of the python libraries. These things come with experience.  So get yourself some experience…write some darn code!

Thank You for S/W Documentation

I’m a believer in s/w documentation.  I realize that view is not shared by all s/w developers (especially in the Agile world in which we live), but in my opinion, generating documentation for your code is just like generating tests for your code: it’s 100% part of being a professional s/w developer.  It’s your responsibility, and you should take pride in it.

I was reminded of this today and smiled inwardly when I came across the following statement in Section 7.1 of Python’s excellent documentation about its documentation:

“Python’s documentation has long been considered to be good for a free programming language. There are a number of reasons for this, the most important being the early commitment of Python’s creator, Guido van Rossum, to providing documentation on the language and its libraries, and the continuing involvement of the user community in providing assistance for creating and maintaining documentation.”

I could not agree more.  I’ve gone to that Python documentation literally 1000’s of times.  Where would we be without it?  OK, maybe its not 100% fair to compare the documentation requirements of the Python language to that of the s/w widget that you are currently building, but I still think the analogy is there: Documentation must be created, and it must be created by people.

The documentation and tools to search for documentation that we have as developers today are astounding. From simple Google searches, to StackOverflow, to formal documentation for Apple and Android platforms, Python, etc.  This documentation is NOT self-created (nor is self-creation as a philosophical construct possible — debate for another day).  This documentation was created by all kinds of contributors who took time and wrote it.  Some of it was created by people who were paid to do it specifically.  Some was created by the developers as part of their development.  And bunches and bunches of it was created by the open source, project, and forum communities across the interweb.

Documentation is a major key to both usability and maintainability.  Why?  I’m generalizing here, but if you are a developer on a team, it’s likely that the code you developed will be:

• Interfaced to and used by others (either other developers or users), and
• Maintained by or at least shared with other developers

In my opinion, the code plus some sort of documentation that describes the intention behind the code is critical to help others use and maintain it.  The more your colleagues and users can determine on their own, the less you have to get involved later on.  The classic win-win.

And guess what?

Six months from now when you yourself open that module back up, you may be looking at the comments/documentation yourself to figure out just what the ‘h’-‘e’-‘double-hockey sticks’ you were thinking when you wrote that code.

So what does documentation look like?

Well, that’s really a project dependent question.  However, what I can say is that the minimum set of documentation for all source code should be:

• A header block at the top of files/modules and for all classes and functions within files that contains a description of the file/module/class/function, its inputs and outputs, and any design and use assumptions and considerations.  For example, it’s useful to note when a particular module is not performing any range checking because its intended use is in a system that checks in a different layer.
• Correctly commented code.  The only thing worse than uncommented code, is incorrectly commented code.

A little more on the topic of commented code…What about the concept of “we are developers, we should be able to read the code and figure out what it does.”  Well…I agree completely.  I think judicious use of comments inline may be useful (again as long as they are correct), but not absolutely necessary.  However, what IS important inline are comments that describe intentions or the “why’s” that are not inherently obvious from the code itself.

So what other kind of documentation should be produced?

Again, its project dependent, but here are some guidelines:

• Developer and User Documentation: Overall developer or user level documentation for an application/library/language is best created manually and published in a web-based format.  For example, the 3 that I mentioned previously: Apple, Android, and Python.  In addition, I think it’s best if the “source” for the documentation is actually created in some markup/down text format, kept under source code control, and then rendered and published via automatic tools to a Wiki, direct to web server, or some other web-based service.  This is not absolutely necessary, but I think its a real solid idea.  This allows easy tracking and publications of differences between releases, plus rollbacks when documentation errors and issues are found.
• Modules/Classes/Libraries API Documentation: For modules/classes/libraries that are to be used as part of larger systems (i.e., they have an API), there should be API documentation, and it should also be web-based.  Normally I think the best approach for this documentation is to use a tool that auto-generates the API documentation from comment-tagged source code, such as Doxygen and PyDocs. This is not always possible given the particular language for the project, but these methods should absolutely be employed when available.
• README’s and Release Notes: README’s and Release Notes should be in text or web-based format. Also, these should be generated automatically (or mostly automatically) from the SCM tool diff’s.  Why do extra work each release?  Take some time and write a script that will get the README or Release Notes directly from parsing through the SCM tool differences.  Maybe you can’t get it 100%, but you can get it close.

So what about good old-fashioned Word or other offline documentation format?  Well, sometimes given the circumstances, it’s still the proper format.  However, given the way we as developers use documentation, it’s usually undesireable.  It’s inherently unsearchable and difficult to manage in an SCM world.  But again…sometimes its the only way.

That about wraps it up for me, for now…

Subversion Commit (or Other Action) with a Different Username

Sometimes you need to do an subversion commit, or other action, as a different username than the one you used to checkout the repository.  This can happen for a variety of reasons, but maybe you’re using a coworker’s machine or working directory, or your group uses a common user account for performing certain actions.  In any case, here is how you do it:

$ svn --username <differentUserName> commit

You will then be prompted to enter the password for that username. You MUST use a username that has credentials for the repository.

You can head off the prompting of the password by including it in the command line, as follows:

$ svn --username <differentUserName> --password <differentPassword> commit

You can change commit to other svn commands such as checkout as well.

See the svn manual for more information.