What Is Your Definition Of A Good Comment

What do you feel about code commenting and how do you comment your code?

Asad Awadia's photo

A lot of times you will hear - you should comment - why you are doing something not what you are doing. Disregard that.

Your comments should be a guide or a walkthrough of the code. When I read my old code back - I am reading the comments and not even looking at the code because the comments guide me to where I need to be. Once I get to a certain place in the comments - I know that's where I need to add the code to add a feature or fix the bug because the comments walked me through the entire flow.

I also add hacky code warnings so people don't copy it to other places in the code base and also add documentation about hidden behaviour right in the code path so the next person knows what is going on. It helps with things that aren't obvious such as negative caching in DAX

Show +6 replies
Josiah Augustine's photo

Thanks a lot for the feedback and the example. As for learning another language, which one would you recommend?

Asad Awadia

Asad Awadia's photo

One or two of the three modern programming languages - Go, Rust, and Kotlin. I would do Kotlin first and then Go and leave Rust unless you are really looking to get into systems programming.

Then once you have those down - start by question where do you see yourself as a developer? Frontend, Backend, SRE, or Data?

Then depending on the domain you will have to learn a bunch more stuff for that area.

Josiah Augustine

Benito Kestelman's photo

I'm a big fan of commenting a lot so my teammates and I can easily understand our code without having to parse it - one of the most frustrating things when reading other people's code is lack of comments - but actually some of the best advice on comments I've heard is about writing fewer comments:

  1. Most of your code should be clear enough without comments. If you are commenting a lot because your code is hard to understand, this should be a red flag that you need to organize it better (e.g. by breaking it up into smaller functions).
  2. Make sure to keep comments up to date with the code. The only worse thing than no comments is comments that are wrong! (following rule 1 helps with this)
Josiah Augustine's photo

Please can you give me an elaborate example of how you comment your code. I write code and don't know what to comment. An example would give me a good pointer. Thanks

Seshank A's photo

I feel we gave 2 goals : 1) The one who has written it should be able to understand it after 2 weeks, 2 months and 2 years later too. 2) Someone who has knowledge about the module should also be able to understand.