Re: What is your best preference on Comment Style?

Posted 18 May 2017 - 11:55 AM

I'm not a big fan of comments. I prefer code that's written in a way that makes the intent clear and comments largely unnecessary. I would still use comments if I was going to produce documentation for the interfaces and then I'd just stick with whatever the language conventions were (e.g. in Java/Scala it's /* and */). I wouldn't put any history in comments, either - that's what version control is for.

Re: What is your best preference on Comment Style?

Posted 18 May 2017 - 12:03 PM

Ideally, the comment should make it clear what it would take to delete the comment. That is, every comment should be considered as a "TO DO", or a promise to clean up the code. And any time you touch code with a comment, you should be looking for a way to make that comment go away.

At least, this is the standard reasoning under the "Clean Code" mentality, which supposes that code should be written to communicate its intent to the reader, and therefore that comments should be superfluous and considered either as bugs or at least as indications of places that need improvement.

Re: What is your best preference on Comment Style?

Posted 18 May 2017 - 12:26 PM

Guys, I don't think you have a right visual of what a "Comment" is.

I'll be a little bit or more ... absolute at this one and please excuse me. But I believe so much that you're having an extremely bad behaviour on not writing comments. It's just that the way you say "I think best comments are no comments" looks somehow arrogant to me and trying to look cool. Excuse me if that was not in your intentions.

Comments Benefits:

As jon.kiparsky said, firstly it is a promise of what the function should be doing. That it's not going to do anything more or anything less than what it promises to do. It's a contract between the user of the function and the developer himself.

Comments are written in pure English (or whatever) language. Which makes your code automatically more clear. Especially when we use a unique style for our comments like a Box Comment.

Comments can be visible on the minimap (weak argument but it's still a "pro")

Comments tell you what the function is exactly doing without you having to inspect it all over

They save precious time on development and bug detection. Like ... MUCH time. Having comments lets you know what a piece of code is intended to do. Without having them you wouldn't know what they should do so you don't know if there's actually a bug! That's CRITICAL.

By having comments, you can say when this piece of code was lastly edited, which is a pretty precious information right there! For example, if you have a bug that you didn't have before a specific date, you can tell if this piece of code may be responsible for it! Bang! Another Time-Saving service!

You can tell who created this piece of code and who you have to contact with so he can explain why he created this, how this works etc. Time Saving again! Instead of inspecting on your own ...

So much more ... ! And they make your code look much more cleaner ...

I don't understand, what makes you believe "not writing comments" is a good idea?

Re: What is your best preference on Comment Style?

Posted 18 May 2017 - 12:32 PM

A bit of that is overly romanticizing comments on the same plane as folk who demonize comments and want to burn them out.

Meh - the world is a fuzzy place. I look at trying to write code in such a way that comments are not needed, but shit happens and some logic gets tricky, changes, or needs some 'splaining for my future self on why I did this path versus another obvious one.

Sure there should be a source control log, but those systems change or may not be available to go back ten years.. same with documentation that should hike with the project but fails.

In the end trying to write code that shouldn't need more explanation is a great goal, but I am certainly not going to go on a witch hunt to achieve that 100% of the time.

Re: What is your best preference on Comment Style?

Posted 18 May 2017 - 12:36 PM

I disagree with several points above. Firstly, on functions for example, they should be doing one thing and one thing only. A good name tells me what that thing is (and of course that will be domain specific). A function should only have one level of abstraction in it, following the "step down rule" that Bob Martin refers to in Clean Code. Both of these things make it clear what that code does without having to dig too much into the details until one really needs them.

As for finding bugs, we have tests that make sure that the behaviour is correct. If there's a bug, we'll have fast feedback because tests will fail (of course, we can't guarantee that we won't make mistakes in tests, but we're glad for the safety net).

One of the problems with comments is that they can get out of sync with the code - someone may change something and forget or not bother to update the comment. The only real source of truth, that is, the only thing that tells you what the software does now, is the code that's currently there.

Also, again, we have version control to keep track of who changed what, when and why.

Re: What is your best preference on Comment Style?

Posted 18 May 2017 - 12:38 PM

You obviously have strong opinions on the subject. It would have been better if you had provided these opinions in the OP rather than just the very open question of "What's your Commenting Style Guide? "

Your points are countered by writing clean, clear, code and using version control. And resolving bugs as early as possible.

Re: What is your best preference on Comment Style?

Posted 18 May 2017 - 12:44 PM

modi123_1, on 18 May 2017 - 12:32 PM, said:

A bit of that is overly romanticizing comments on the same plane as folk who demonize comments and want to burn them out.

Meh - the world is a fuzzy place. I look at trying to write code in such a way that comments are not needed, but shit happens and some logic gets tricky, changes, or needs some 'splaining for my future self on why I did this path versus another obvious one.

Sure there should be a source control log, but those systems change or may not be available to go back ten years.. same with documentation that should hike with the project but fails.

In the end trying to write code that shouldn't need more explanation is a great goal, but I am certainly not going to go on a witch hunt to achieve that 100% of the time.

I agree that my reply is a little bit "over romanticizing" comments, but it's not like I'm saying something that it's not true. I just made it look a little bit more useful.
On the other edge though, not writing comments is not only useless ... it's making your life extremely hard for no reason. Not only your life, all the people's life that are reading your code.

I mean writing many comments is never a bad idea (except if you write whole paragraphs), but writing no comments? Man, that's a mess for everyone!

It is a fact that you should be trying to make such code that makes comments useless, but

You can't always rely to the second hand programmer that he is gonna use the function correctly

You can't always rely on yourself that you will not add more or less characteristics to the function than it actually needs

And as I said previously comments are not only to describe what a piece of code does, but it's a way to make a documentation and to record everything that happens in your code.

Upvoted though, but writing functions that don't need comments to explain them,
a ) is not always easy and as you said it's a "Witch Handing" and waste of precious time in production
b ) You can't rely on the Programmer's Perception that he will understand what the function is indented to do. There were several times I needed C# Linq's commentary to understand what "Where" and such functions do because I was forgetting by the time because I wasn't using them.

It's just my opinion that ... Assuming that the second hand programmer or even you after a long time will understand what a piece of code or a function does is a VERY bad idea. Not arguing at this ... anymore ... you have your opinions ... I have mine. It's not like we're arguing if 1+1=2 here.
It's just me that thinks it's a bad idea not to make comments and assuming things.

Re: What is your best preference on Comment Style?

Posted 18 May 2017 - 12:49 PM

It's not necessarily true when you line up the hypothetical. I think you are cross viewing the hypothetical code and comments. If you have mediocre code then yes - comments would help out everyone. Conversely if you have overly the top clear code then you shouldn't need comments.

Personally I won't write my comments for some fictitious sub par programmer in the future. I write it for my current clod level as well as the elevated level of those on my team.

Re: What is your best preference on Comment Style?

Posted 18 May 2017 - 12:57 PM

Quote

As jon.kiparsky said, firstly it is a promise of what the function should be doing.

Just to make this clear, this is not what I said at all. Many people like to have a human-language string that makes this sort of promise. I prefer to have a name that indicates clearly what the function should be doing. This means that every time I find this function in the code, I have a correct idea of what to expect from it and I don't have to go chasing through the codebase to find it.

Quote

Having comments lets you know what a piece of code is intended to do. Without having them you wouldn't know what they should do so you don't know if there's actually a bug! That's CRITICAL.

Again, I think this is the job of the function name. If I can't tell from the name what it is you want this function to do, it's not getting by code review if I have anything to say about it.

Quote

In the end trying to write code that shouldn't need more explanation is a great goal, but I am certainly not going to go on a witch hunt to achieve that 100% of the time.

It's worth a try, though. We set that as a standard on my team, and we hold each other to it. We don't get it 100% of the time, but I would say that our code has better names than any other place I've worked, because it has to be approved by three people who are willing to stop and think about each name and make sure they understand it. This does not slow us down, because a, we seldom have to reconsider a name and b, when we're working we can understand the code correctly without a lot of decoding, so we go a lot faster and make fewer mistakes.

Quote

By having comments, you can say when this piece of code was lastly edited, which is a pretty precious information right there! For example, if you have a bug that you didn't have before a specific date, you can tell if this piece of code may be responsible for it! Bang! Another Time-Saving service!

git blame. Which is guaranteed to be up to date, although if people move code around a lot it might require some tracking. This also tells you who changed the code, when, and why, all the way back to the dawn of time. Your comment just tells you the last person who touched it.

Now I should say, you don't have to like the "Clean Code" style. That's fine, it's just one approach to code. But overall, I find it's an effective way to work, so I recommend it.

But in general, the only time I will put in a wordy comment will be to identify why the code looks wrong:

// BUG-1234: Force the locale to be US English instead of the
// the current user locale due to a bug in the library
// that does not understand commas as decimal points.
// Furthermore, it does not support custom locale
// preferences. It is all or nothing.
// TODO: Find updated library or change to a new one.
SomeBrokenLibrary.SetLocale("en-us");