Pages

Monday, October 3, 2011

Don't be clueless when it comes to comments

A lot of developers seem to be clueless about what comments to include in code. And that makes someone who is unlucky enough to have to decipher that code clueless as well. At a minimum, functions should include a description of what they're for. Furthermore, sections of code that aren't self-explanatory should be explained. And you should describe everything that a developer needs to know regarding what arguments to pass into your functions.
Comments warning about any limitations regarding arguments are particularly important. This is especially true for languages that aren't strongly-typed, such as JavaScript and VBScript. In these languages, there's not much you can do to prevent a developer from passing any kind of datatype into your functions. Of course, for added robustness, you can make your code check that the arguments fit expectations. However, in some cases the added checking may not always be worth the extra time spent in coding and processing. So you may need to fall back on just writing clear comments. //Got that?

No comments:

Post a Comment

Note: Only a member of this blog may post a comment.