Comments Do Have a Place in Code

Hot Topic 🔥

This is always a huge topic in any development team. I can guarantee you at some point in their career a developer has had an heated discussion around whether to add comments or not.

And here's my thoughts.. wait for it ...

I believe code comments have a time and place! Comments are great, they do no harm and should be used whenever the developer feels they're suitable to explain their code.

Other common ideologies

1. Code shouldn't need comments and should be written in a way that doesn't require comments.

2. Everything should be commented, from classes, property names, methods/functions, method code.

Ok so let's look at these in more detail.

No comments at all:

This ideology focuses around naming classes, methods, and variables with fully descriptive names. This means there is no need for a comment describing what it does.
Let's take this example

var x = GetDate(tomorrowsDate);
Console.WriteLine(x);

public string GetDate(DateTime date){
   return date.DayOfWeek;
} 

This isn't great as the method is poorly named and ambiguous / misleading as to what date it returns. To avoid using comments , "no comment Devs" would write it as so.

var dayOfWeek = GetDayOfWeekFromDate(tomorrowsDate);
Console.WriteLine(dayOfWeek);

public string GetDayOfWeekFromDate(DateTime date){
   return date.DayOfWeek;
}

This example although be it a simple one illustrates the point well. There is no need to add any comments as we know exactly what is going to be returned, and what the method is going to do.

Comment Everything

This is where dev's believe that everything should be commented, as an example:

//get day of the week from tomorrows date
var day = getDayOfTheWeek(tomorrowsDate);
Console.WriteLine(day);

// method returns the day of the week as string from provided datetime object
public string GetDayOfTheWeek(DateTime date){
   return date.DayOfWeek;
}

I've seen some devs even comment their class properties like so:

public class User {
//Date user was created
public DateTime CreateDate {get;set;}

//Username of User
public string Username {get;set;}

}

You may find this hilariously stupid, but I've seen this in solutions before.

For me this is overkill, you can see what the variable is called and the method. You can therefore easily deduce what the code is doing without the need for all the detailed comments.

My Opinion - There's a place and a time

Don't over use comments, there's a time and a place for them. I utilise comments when the code is not self explanatory. Some systems I've worked on in the past can be convoluted or have some "weird" code in there for very specific situations.

Perhaps there's been a time where you tried something but it wouldn't work due to system limitations or something. You could leave a quick comment explaining this to your future self or other developers.

A very basic example would be:

public void SaveUser(User user){
  user.DateCreated = DateTime.Now();
  user.Role = Roles.Sysadmin;

  //need to save user and role before saving user due to system constraints.
  Db.UserRoles.Add(user);
  Db.SaveChanges();

  Db.Users.Add(user);
  Db.SaveChanges();
}

Yes the sceptics out there would argue this is poor code design, however we all know that sometimes we come across code situations where not everything can be textbook, without re-writing huge parts of legacy systems. This way we can still write new code, and leave explanations of why we he have to do something which, to others may seem weird.

The argument here is that without any comments the next developer to come a long, would be thinking why are they doing this, why are they calling the database twice etc. They may then revert the code, and the code would then fail.

For me it's about balance, and I try and follow these golden comment rules:

1. Use well named variables, methods, and classes
2. Write logical code which can developers can deduce what you're doing by the variable names and return types.
3. Utilise brief comments to explain what the code is doing, but mainly why.
4. Do NOT just comment everything for the sake of commenting - it's not necessary.
5. Don't write humorous comments to try and make devs laugh - it's just unprofessional and wastes space.

In Summary

Balance your well written, well named code with explanatory comments. If you write "nice" code with well written names , and small comments, I can guarantee that other devs will thank you for it , and the code will become more manageable, and quicker to debug.