Clean Code Thoughts — Comments

Ellison Alves
Jul 20, 2017 · 4 min read

It is time to talk about code comments. I think they can be basically three things: good, bad and funny (especially when you don’t have to deal with it). Now, let’s think about “Which kind of problems comments are trying to solve?”.

  1. We can change software behavior quickly and test it, even in production. (and we can forget that “feature” there).
  2. We can make jokes to colleagues.
  3. We can write TODOs.
  4. We can write software license in the code.
  5. Ok! We are able to provide some information to another developer. Usually, this information is needed because we are not always able to express ourselves without them. Why? Sometimes due to the programming language, the dubious nature of the problem or even our language, lack of knowledge and I am pretty sure we can grow this list easily.

When Comments could be a GOOD idea

Legal Comments

Explanation of intent or clarification

Warning consequences and Amplification

An example worth more than 1000 words. :)

//
// Dear maintainer:
//
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
//
// total_hours_wasted_here = 42
//

TODO comments

JavaDocs and Public APIS

When Comments could be a BAD idea

Redundant

Misleading

When you can use a function or a variable

Commented Code

Relevant points about comments

  • Programmers are not always used to maintain comments;
  • Programmers are trained to skip useless comments;
  • Rules that compel programmers to document everything (methods, variables etc) will encourage them to write bad comments as well as ignore most of comments.
  • Usually, comments can become inaccurate and useless;
  • The code can be self explanatory removing the need to insert more information than necessary;
  • As software developers, we are writers. Therefore, it is important to improve our code writing ability in order to do it more expressively.
  • If you can’t be clear writing code you probably won’t write clean comments as well;
  • If the code is not well written, instead of try to explain it in comments, put your energy refactoring it;
  • Public APIs should have documentation. Therefore, make a good use of comments in order to write it clear.

Conclusion

Last but not least, take a look to these comments! :)

Devtrail

sharing thoughts and lessons learned about software development

)

Ellison Alves

Written by

A software developer, guitar player, photography lover and gamer when possible :)

Devtrail

Devtrail

sharing thoughts and lessons learned about software development

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade