Comment your Code with Logic and Humour

by Carey on November 16, 2010

Post image for Comment your Code with Logic and Humour
  • Share
  • CevherShare
  • Share

Commenting your code is great for a number of reasons and ultimately it will keep your project maintainable and will save you time in the long run.

However, commenting for the sake of it or explaining every last detail is unnecesary and could actually make your code harder to work with and less maintainable.

Consider the following pointers:

Don’t comment for the sake of it.
If your code is readable and is doing nothing you wouldn’t come across ten times a day, don’t waste your time in writing it and somebody elses time in reading it.

Make it readable.
Avoid abbreviations and shortcuts in your comments that only you will know. The general rule here is write the comments for someone else, not for yourself

Update your comments.
If your modifying the code, make sure the comments represent the new logic. If you don’t have time to update the comments, as a last resort delete the existing ones – at least you won’t send people down the wrong path.

Keep it short and sweet.
Don’t write an essay and keep to the point. Long comments won’t get read and will be a waste of time for you.

Give your contact details.
Particularly relevant to web development, keep an email address in their somewhere (i.e. the top of each file) so any future developer can get your help. If you do a good job this can also get your work and recognition.

Inject a bit of humour.
We aren’t robots, add a bit of personality and it may just make the task of updating that little bit easier for you or someone else.

{ 2 comments… read them below or add one }

vask February 23, 2007 at 3:17 am

Comments should be a part of programming, for me it is important as any other part.

Reply

perez_opal February 23, 2007 at 7:24 pm

Sometimes you just don’t have the time and if you know for a fact the comments will not be used, I think it is more pragmatic to just forget them.

Reply

Leave a Comment

Previous post:

Next post: