Code Comments

General debates - politics, philosophy, religion, whatever - stick them in here.
User avatar
drakkos
Site Admin
Posts: 183
Joined: Fri Aug 17, 2012 3:27 pm
Location: Brechin, Scotland.
Contact:

Code Comments

Postby drakkos » Fri Sep 07, 2012 1:52 pm

'Comments are a form of code repetition'

Discuss.

karras
Posts: 2
Joined: Fri Aug 17, 2012 4:51 pm

Re: Code Comments

Postby karras » Sat Aug 03, 2013 10:05 pm

You're a form of code repetition.

User avatar
drakkos
Site Admin
Posts: 183
Joined: Fri Aug 17, 2012 3:27 pm
Location: Brechin, Scotland.
Contact:

Re: Code Comments

Postby drakkos » Sat Aug 03, 2013 10:14 pm

Crikey!

Sent from my GT-N7000 using Tapatalk 2

User avatar
hugo
Posts: 40
Joined: Sat Aug 18, 2012 9:31 am
Location: Spain

Re: Code Comments

Postby hugo » Sun Aug 04, 2013 12:00 am

All right, settle down you two.

ror
Posts: 5
Joined: Fri Aug 09, 2013 6:26 pm

Re: Code Comments

Postby ror » Thu Aug 15, 2013 6:59 pm


mercutio
Posts: 3
Joined: Thu Aug 15, 2013 8:28 pm

Re: Code Comments

Postby mercutio » Thu Aug 15, 2013 8:29 pm

Code tells you what's going on, Comments tell you why

User avatar
drakkos
Site Admin
Posts: 183
Joined: Fri Aug 17, 2012 3:27 pm
Location: Brechin, Scotland.
Contact:

Re: Code Comments

Postby drakkos » Tue Aug 27, 2013 10:24 am

That's certainly an ideal case, but in my experience all comments really do in the end is tell you whyv code that doesn't work that way any more worked the way it did. Comment discipline is very low, with myself especially, and it tends to be the case I find that code changes and comments don't.

That's what I mean by code reputation... they double the number off places you need to make changes in code, and mismatching comments can lead to add much confusion as any code mismatch.

Sent from my GT-N7000 using Tapatalk 4

howando
Posts: 5
Joined: Wed May 28, 2014 11:23 pm

Re: Code Comments

Postby howando » Sun Aug 03, 2014 8:29 pm

I think there are two types of comments.

The "bad" ones are like pencil notes in the margin of a book where the printed text can be edited with no regard for the handmade marks. Stuff like "// max width" should probably be dealt with using descriptive variable names. A lot of "// centre the box with respect to the container" type of thing can also be rendered moot by descriptive variable names and good organisation/whitespace. The chances are that a bugfix or a rewrite will render these comments meaningless or even counter productive when encountered in the future.

There is a place for comments as definition of functions or blocks, like chapter summaries. Even though the code can change a little, the summary or abstract shouldn't be effected unless the purpose of the function or code block actually changes. If the purpose is changed then the comments become useless unless updated, but that's also true of any documentation you may have. If you assume that there ought to be at least some documentation on the code function and purpose, including these signposts in the code can allow the actual code makes sense.

Definitely "comment-as-you-go" leads to a lot of entropy, but including some comment on the code can make it a hell of a lot easier to understand what is supposed to be happening when you're updating or debugging.


Return to “Debates”