Use Comment Blocks Before Functions
When you write a function in any programming language there are a number of things you might want to get right within the code. Examples might be:
- trying to have only one entry and exit in a function (although I’ve seen some contrary and sensible examples in Jeremy Keith’s book DOM Scripting)
- properly indenting code to make it more readable
- following naming conventions
- testing the edge cases to see the function works as expected, and
- not misusing recursion like a mad little russian doll gone AWOL (Absent Without Leave)
Also, for the love of my own sanity its really shit practice to have non-meaningful variable names like e, j and fp unless its a standard increment or something very obvious. Remember what is obvious today is tomorrows meltdown! It seems JavaScript and C are two languages where esoteric naming seems to have a cult following that spells guru.
But these aren’t the tips I’m thinking of this morning. Robert Nyman’s post on code assertions got me thinking about writing maintainable functions. I’d like to bring your attention to the humble comment block directly before the function you just wrote… its boring, its even a little tedious, but it will save you a world of pain when you go back to that function in 4 months time or for someone opening your code at a later date.
The importance of robust code that is maintainable can’t be over emphasised. Both internal and external documentation need to be a part of a professional programming regime.
So what might you put inside the function comment block… You might write:
- the date the function was created and the date it was last modified
- who was the author of the function
- at least a very basic description of what the function does (rather just writing “this function gets stuff from the server”), and
- the expected inputs and outputs the function handles (not to be confused with the description)
External documentation might provide further information about who has changed the function and why they did so. Did it have errors or did it get repurposed somehow so that it needed modification? Was there an upgrade to a newer technology or was there a security reason? These can be important artefacts to maintain and save your bacon. You might want to keep timesheets (and in again in German) or somehow record how long it took you to write the function so that you have a growing reference that enhances your ability to quote on future work.
I can see that internal documentation in a web based environment is a grey issue. After all, we’re trying to optimise our code and not bloat it with meaningless irrelevant dates and explanations. I think the career migration from smaller scripts into larger projects will see more emphasis on software engineering principles like quality and maintainability. That comment block can go a long way to improving these aspects of your function. In short, don’t write functions just so you understand them.
January 15th, 2008 at 8:25 pm
[...] going to break anyone’s day typing it in there. The next level of internal documentation are comments before each method or function. This should at least describe the function and it would be good to have the expected inputs and [...]