It can be tempting to wait until all of your work is completed before adding precious, insightful comments into your code.  The reality is, you will never have a better understanding of what your code does or why you wrote a particular method the way you did than when you are in the process of writing it.

/* Commenting Your Code */

Tue Nov 15, 2016

Do it now before you forget what you did.  No, really.

Woman Coding
“I’ll add my comments later, when everything is done.”

It can be tempting to wait until all of your work is completed before adding precious, insightful comments into your code.  The reality is, you will never have a better understanding of what your code does or why you wrote a particular method the way you did than when you are in the process of writing it.

It can be extremely hard to get into the same mindset you were in when you were “in the zone” of constructing that tricky loop that was difficult to get just right.  And often, even though you probably remember what a section of code is doing, you may not always remember why you did it that way after the fact.

Besides, let’s be completely honest.  Other tasks come up, bugs surface, priorities change.  Before you know it, commenting that code you wrote a week ago becomes less and less important in your mind compared to all of the other projects you are juggling.  Then one day in the not-too-distant future, Sandra that sits next to you is either silently cursing you in her mind (or maybe out loud) because she has to make changes to the code that you did not afford her the common courtesy of properly notating.

The same things can be said for proper documentation outside of your code.  Faithfully updating your knowledge repository, whether it be Confluence or a Wiki page, will help save someone else a lot of time when trying understand your application or feature.  In the long run, proper commenting and documentation will save you time in the long run, because you will probably get less questions and requests for help.

tl;dr: code, comment, document, repeat.

Michael Reidy Headshot
Michael Reidy
Web Consultant

x