Techniques:
Chances are if you went to college to learn to write software they may have emphasized self-documenting code (aka naming your for loop variable i or x when looping through a list of table rows you could've named the variable rowIndex or something more definitive). If not, it's a great idea to try to implement self-documenting coding techniques. Your present and future colleagues will appreciate you more for that one.
Another option is to put in the occasional comment or two. Generally speaking if I can't rationalize what an obscure block of code is doing (happens quite a bit out in the wild) I throw in at least some documentation on what that block of code is attempting to do. That way future me and present me can be on the same page quicker than not so future me can determine what action to do next to it more efficiently than if it the coding block wasn't documented.
The last option is putting your pseudo-code into comments near your obscure block(s) of code. If nothing else future you (or your colleagues) can try to see what present you was attempting to do in the source code. This form of documentation is one I've been trying to implement in the past six months or so, so far I've used it a few times when the self-documenting code as well as the comments for each block might now give future me (or a colleague) an idea of what present me was attempting to create.
Conclusions
Documenting your code might seem like a bit of a hassle but in the long term it'll save future you (and potentially your colleagues) time to debug/determine what your present code is doing.
Shout outs:
I have to give credit to Peter Hyde and Bobby Russell for blogging along for quite some time now, keep up the great work guys!
I love self-documenting code. Variable, property and function names that make sense are one of the easiest ways to do accomplish this. Thanks for the common sense tips!
ReplyDelete