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

C# Enum as bit field

Bit field enum Whenever you wish to express combinations of properties of an object, bit fields are a good way to accomplish this. As a simple example, consider a file in the file system. It can be Readable , Writable , Hidden or a combination these. The different attributes can be defined as an enum : [Flags] public enum FileAttribute {   None      = 0b0000;   Readable  = 0b0001;   Writeable = 0b0010;   Hidden    = 0b0100; } To indicate that this enum is expected to be used as a bit field I have defined it with the FlagsAttribute . It is important to understand that the FlagsAttribute does nothing more than making some changes to how the ToString method of the enum works, making it possible to print out all flags. It does not introduce any validation or special treatment of the enum in any other way. I have defined the values of the different fields of the enum using binary representation, this should make it even more clear that this is a bit field and which bi
Skicka en kommentar
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