Fortsätt till huvudinnehåll

Some comments on comments

Recently we have been discussing coding guidelines at work. A topic that often pops up during such discussions are Comments. What should be commented, how should the comments be formulated etc.

Personally I have the following preferences when it comes to comments in code:

  • A comment should explain why a piece of code does what it does, not what the code does.
  • If you feel a piece of code needs a comment. See if it is possible to make the code easier to understand rather than commenting it.
  • Only use special mark-up like Doxygen if you actually generate documentation from it. I have seen cases where Doxygen-like syntax was used all over the code, only obfuscating the text.
  • Public interfaces intended for users of your lib/class should be documented, and documented well.
  • Internal/private interfaces and classes does not require documentation. Put effort on making the code really easy to understand rather than adding a bunch of comments.
  • Keep comments short and clear.
Happy commenting!

Kommentarer

Skicka en kommentar

Populära inlägg i den här bloggen

Does TDD really improve software quality?

I have asked myself this question several times, and searched for answers, without coming up with any clear answer. Therefore I have decided to go hard core TDD for a longer period of time (at least 6 months) to really evaluate the effects. There are several things that I find confusing when it comes to TDD. One example is what actually defines a unit test. What is a "unit" anyway? After reading a bit about it I found a text claiming that the "unit" is "a unit of work", i.e. something quite small. Like converting a string to UPPERCASE or splitting a string into an ['a','r', 'r', 'a', 'y'] of chars. This work is usually performed by a single call to a single method in a single, isolated, class. So, what does it mean that a class is isolated? Does it mean that it doesn't have any dependencies to other classes? NO! In the context of TDD it means that any dependencies are supplied by the test environment, for exa...
3 kommentarer
Läs mer

Codility tasks - Part I

I was recently faced with two codility tasks when applying for a job as an Embedded Software Engineer. For those of you who arn't familiar with Codility you can check out their website here:  www.codility.com Task one - Dominator The first task was called Dominator. The goal was to, given a std::vector of integers, find an integer that occurs in more than half of the positions in the vector. If no dominator was found -1 should be returned. My approach was to loop through the vector from the first to the last element, using a std::map to count the number of occurences of each integer. If the count ever reached above half the size of the vector I stopped and returned that integer and if I reached the end without finding a dominator I returned -1. So was that a good approach? Well, the reviewer at the company rated the solution as 'pretty ok'. His preferred solution was store the first integer in the array and set a counter to 1. Then loop through the remaining i...
7 kommentarer
Läs mer

Some links to look more at

This post is a "note to self" to look more into these links: https://blog.idrsolutions.com/2013/09/5-tools-to-help-you-write-better-java-code/ https://blog.idrsolutions.com/2014/06/java-performance-tuning-tools/ I am looking for tools for static code- and performance analysis on Java code.
6 kommentarer
Läs mer