5

I've been working on a project for about a month now. I am extremely familiar with the code and understand it to the extent where I feel that it is so easy to understand, that most methods don't need comments in my opinion. I can't tell if it's because it is actually simple code or that I am just very well practice on how it runs. How do you draw the line between simple code and code that needs comments?

Bender Bending
  • 169
  • 5
  • 4
    see also [How would you know if you've written readable and easily maintainable code?](https://softwareengineering.stackexchange.com/q/141005/31260) – gnat Jun 14 '17 at 14:03
  • 3
    Note to the OP: just because this is a duplicate doesn't mean you should feel bad about it being closed or feel you should delete it. It's a good question that will help lead folk to answers from previous, similar questions. – David Arno Jun 14 '17 at 15:13
  • 3
    I don't feel like this is an exact duplicate, particularly because the accepted answer recommends peer reviewing, which is difficult for a solo reviewer unless they go to a site like Code Review SE. I know that answers shouldn't affect whether or not something is a duplicate in theory, but it feels like this should be left open. – RubberDuck Jun 14 '17 at 15:49
  • Thanks @DavidArno and @RubberDuck! The links that the other guys provided were helpful as well. – Bender Bending Jun 14 '17 at 16:51

3 Answers3

2

If the code is simple it should be easy to comnent. Just do it, in full gramnatically correct sentences, using consistent snd appropriate nomenclature.

On some occaissions you may find it hard after all to write a good documentation header or you will find a method that does more than it should.

Taking documenting seriously leads to better code. It strengthens your design by forcing you to express your logic in a different language. If the design still makes sense when you are done you should be good. If it starts feeling wrong or you are having a hard time coming up with a clear description, you still have some work to do.

And last but not least, it will make your code more accessible, if not to someone else to yourself after you forgot what it did.

If you write in C#.NET, check out StyleCop. I like that. But there should be something similar for any language.

Martin Maat
  • 18,218
  • 3
  • 30
  • 57
  • Thanks. It is hard to figure out what lines are and are not worth commenting on, I feel as though if I added to many comments the actual code page would be 50% code and 50% comments. Your advice will help me continuing developing this project further. – Bender Bending Jun 14 '17 at 21:07
  • 1
    @Bender In my answer I was talking primarily about class member documentation. In code bodies you will often have several blocks that represent steps in the logic. You could briefly comment each block and the comments together should tell the method's story. Ideally you would start by writing these comments in an empty code body, thus setting the stage for your implementation and then insert the code blocks. – Martin Maat Jun 14 '17 at 21:36
1

I'm in the same situation. After working on code for a while, you become extremely familiar with it. You know how it works. But imagine if you were to read something that someone else wrote for the first time. Comments would make that code a heck of lot easier to read. What I generally like to do (and I have very limited experience) is to make a higher level comment for algorithms and functions that explains what they are generally doing. And then if there is a line of code that does something more complex, like some kind of calculation or something, then include a comment explaining what is going on. Hope this helps.

namarino41
  • 119
  • 1
  • 13
-3

Simple. always comment and put an auto mated check which prevents code with no comments being checked in.

Advanced programmers might start skipping comments which are the same as a function or variable name.

Ewan
  • 70,664
  • 5
  • 76
  • 161
  • 1
    That is a terrible idea. People will just add useless comments in order to be able to check in. This will make the code worse. – JacquesB Jun 14 '17 at 19:29
  • unfortunately untill you can get a machine to grade your comments its the best you can do. As long as you keep it fairly loose you should avoid the //The Customer of this Company style useless comments – Ewan Jun 14 '17 at 20:42