Questions about writing comments in code.

learn more… | top users | synonyms

4
votes
2answers
180 views

Distinguish different type of Comments

I would like to provide design decisions in the comments as well. I want design decision comments to be distinguishable from function contract comments, on cursory examination of source code. How to ...
5
votes
6answers
448 views

How much commenting is better for coding? [duplicate]

I don't have a formal computer science education, meaning that I did not study computer science topics in a university. However, I work at a programming job and write a reasonable amount of code. ...
4
votes
6answers
326 views

Should an Else statement be used just for a comment?

I came across the following in some sample code: if (urlStr) { NSImage *iconImage = [[NSWorkspace sharedWorkspace] iconForFile:urlStr]; node.nodeIcon = iconImage; } else { // it's a ...
1
vote
1answer
246 views

Does anybody still use TODO for writing code later on? [closed]

Statement I often find myself still writing the following statement all over my code: // TODO: (the work that needs done) I do this in order to flag that I need to come back and do something later ...
2
votes
5answers
816 views

Best way of writing comments in code [closed]

I was wondering how one should write comments in code. I mean, should a comment be a descriptive of what is done in code, like : //we have got array, now we iterate over it. code to iterate array ...
41
votes
9answers
30k views

What does XXX mean in a comment? [closed]

What do people generally mean whenever you see XXX in a comment. Occasionally, I'll see a comment like this: # XXX - This widget really should frobulate the whatsit Of course, I can tell what the ...
-1
votes
4answers
219 views

Emphasize Some Comments - but not Dirty the Code

I'm having trouble structuring my comments at the moment. I have major sections of the code that, when scrolling through the document, I want to be able to see those stand out. Examples: This is ...
171
votes
23answers
16k views

How can I deal with a team member who dislikes making comments in code?

One of my team members consistently avoids making comments in his code. His code is not self-documenting, and other programmers have a difficult time understanding his code. I have asked him ...
36
votes
13answers
11k views

Is commented out code really always bad? [duplicate]

Practically every text on code quality I've read agrees that commented out code is a bad thing. The usual example is that someone changed a line of code and left the old line there as a comment, ...
73
votes
9answers
10k views

Clean Code comments vs class documentation

I'm having some discussions with my new colleagues regarding commenting. We both like Clean Code, and I'm perfectly fine with the fact that inline code comments should be avoided and that class and ...
1
vote
2answers
168 views

What's the noun for the result of an iteration?

I'm commenting some code right now, and I'm looking for a word meaning the thing being iterated over. Iterator is an object performing an iteration, but what's the object that the iterator is ...
0
votes
3answers
123 views

Should method comments be written as if everything will work?

If I have a method to look for a valid email address in an array, that could either: Return the email address Return false if an email wasn't found. Throw an exception if an email was found, but it ...
0
votes
4answers
258 views

Deciphering foreign code [duplicate]

What is the best strategy to go about understanding some one else's code for a medium sized project, if the code is not well documented and does not adhere to many coding standards?
10
votes
5answers
1k views

Annotate source code with diagrams as comments

I write a lot of (primarily c++ and javascript) code that touches upon computational geometry and graphics and those kinds of topics, so I have found that visual diagrams have been an indispensable ...
1
vote
7answers
1k views

Should you use “internal abbreviations” in code comments? [closed]

Should you use "internal abbreviations/slang" inside comments, that is, abbreviations and slang people outside the project could have trouble understanding, for instance, using something like //NYI ...
2
votes
2answers
617 views

Documenting the effect of std::move

As my team move towards embracing the new features in C++11, I'm struggling with how to make the side-effects of std::move self-documenting in the code. The issue is that an object that has been ...
4
votes
3answers
832 views

How should one properly comment and license a set of code files before uploading to the public? [duplicate]

I've written a decent chunk of code over the past few days and I'm ready to git init it and push it to github. But before I do so, I want to do this the "correct" way in case anyone else wants to use ...
68
votes
17answers
14k views

Do TODO comments make sense? [closed]

I am working on a fairly big project and got the task to do some translations for it. There were tons of labels that haven't been translated and while I was digging through the code I found this ...
43
votes
11answers
15k views

Why are /// comment blocks important?

Someone once said we should prefix all our methods with the /// <summary> comment blocks (C#) but did not explain why. I started to use them and found they annoyed me quite a bit, so stopped ...
28
votes
4answers
3k views

How are comments usually parsed?

How are comments generally treated in programming languages and markup? I am writing a parser for some custom markup language and want to follow the principle of least surprise, so I'm trying to ...
16
votes
6answers
5k views

Best practices in comment writing and documentation

Commenting nowadays is easier than ever. In Java, there are some nice techniques for linking comments to classes, and Java IDEs are good at making comment shells for you. Languages like Clojure even ...
2
votes
4answers
130 views

Should actions / methods be conjugated in comments?

For example, which of the following is correct ? // Return hello -- or -- // Returns hello function greeting() { return "Hello"; } I personally never conjugate them but I am wondering how ...
0
votes
1answer
91 views

Should I document expected call-sequences when call-order matters?

In dynamically and weakly-typed languages*, I often find myself with structures like the following pseudocode: class Stateful: # [ various datamembers / attributes / properties / fields / etc. ] ...
-2
votes
4answers
122 views

Best possible way to comment? [closed]

My question is simple, how should I comment during development so that it can be beneficial in the following cases: Understandable for my seniors while code reviewing. Should be able to search my ...
2
votes
2answers
262 views

Is there anything wrong with putting comments in an HTML closing tag?

I often write comments like this <div id="wrapper"> ... </div> <!-- id="wrapper" --> But what if I wrote them like this? <div id="wrapper"> ... </div id="wrapper"> ...
0
votes
3answers
206 views

In the spirit of consistency, is it acceptable to comment everything equally? [closed]

Consistency is something I value (at an OCD perfectionist level to be honest). I can live with not writing any comments and focus on producing good, refactored, readable code -- or, if I must comment, ...
10
votes
4answers
2k views

Why should comments / documentation of a JavaScript function include so much? [duplicate]

I was researching proper commenting practices for JavaScript and highly upvoted answer (+100) cites JSDoc-like commenting. JSDoc promotes comments like this: /** * Represents a book. * @constructor ...
17
votes
6answers
1k views

Writing comments for some small code with rather large background [duplicate]

So I had to write some code related to splitting Bezier curves into parts. I read through several references and particularly referred this rather detailed one. The final code outcome is however ...
22
votes
6answers
3k views

Explaining new or uncommon syntax in comments [duplicate]

As per the title, should I be explaining syntax that I use in my code when I have a reasonable expectation that a developer looking at my code in the future will not be familiar with it? Short caveats ...
67
votes
13answers
9k views

Can commented-out code be valuable documentation?

I wrote the following code: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); ...
9
votes
3answers
238 views

How to refer to specific areas of code in documentation?

I'm about to leave a project, and before I go my boss has asked for me to document code (I've not documented very well). It's not a big deal, the project is not terribly complex. But I'm finding ...
4
votes
3answers
165 views

Is there a difference between the quotes in `help',``help“, 'help' and ”help"?

Sometimes I find in the source code files comments have quotation marks like these ,notice the ` : `help' ``help" For example, these are comments from GNU cat source code file, cat.c: /* Plain ...
1
vote
1answer
163 views

What is ## used for?

I have looked at other questions about this and the general consensus seems to be that ## is used for commenting out code. However, in the Interactive Editor for Python, prefixing a line with ## ...
13
votes
9answers
606 views

Please share experience on how to make the source code easy for other to follow? [closed]

I can write source code in a period of time, but after a while of not touching the project, it takes me time to be familiar with the source code again. Also, other people need some time to study the ...
3
votes
3answers
312 views

Should code comments explain the control flow?

Should comments explain how the application control flow works? For example, the relationships between classes, how this function is used by other functions, and what we are trying to do with these ...
71
votes
17answers
16k views

How can I ask my boss (in a polite way) to comment his code?

I am being taught by my boss (I just finished school and he wanted someone with a little programming experience, so he chose me to train me on what that company specializes in) and started working ...
195
votes
16answers
34k views

What's wrong with comments that explain complex code?

A lot of people claim that "comments should explain 'why', but not 'how'". Others say that "code should be self-documenting" and comments should be scarce. Robert C. Martin claims that (rephrased to ...
8
votes
3answers
1k views

Is reading javadoc preferable to reading source code to familiarise yourself with a library?

I just came across the following in a lab manual at university: You do need to study the interfaces of the classes by generating the javadoc for them so you know what operations are provided (feel ...
0
votes
1answer
70 views

Comments for a class that isn't an entity

According to Java's commenting conventions, classes comments should describe a "thing", rather than "actions". It is easy when the class IS a thing (ex. a Clown), but what if it isn't? In this case, ...
2
votes
4answers
549 views

How does a developer code in anticipation of change? [closed]

I ask this question based on the fact that currently my environment is under constant change due to the type of work we do. We do not always work on a project bases we often have smaller changes that ...
0
votes
2answers
592 views

Commenting Code AS3 - Not being an API

How should I comment a method? What are the best practices on commenting code? Example: /* Checks if a color is allowed in a given point * of the bitmapdata of the current floor * @param value - ...
3
votes
3answers
187 views

Is it misleading to label code as a particular design pattern if it only loosely fits the definition?

Background: I have a rough, but working understanding of ~15 design patterns. It's been my experience using design patterns in my own projects that the resulting implementations usually end up as some ...
19
votes
3answers
6k views

How to solve the problem of nested comments

It appears in not just one language that comments can't be nested. Do you have a good solution for this problem? One workaround in C/C++ and Java is to only use the single-line comment but it becomes ...
-1
votes
7answers
277 views

Single line comments for multiple indented lines of code [closed]

After many years of coding, trying various programming styles, weeding out unreadable or impractical stuff, I still can't figure out one thing: what is the best way to single-line-comment multiple ...
2
votes
1answer
1k views

Possible to Comment on a storyboard?

I recently started working for a company that has me making mockups for an app they'd like to see converted to an iPhone app. I have not been informed as to how all the boards fit together, but I do ...
1
vote
1answer
188 views

Is there a particular coding standard with comments between function name and body?

I'm integrating with a shipping API built in php. They have a strange coding standard where the comments are between the function name and the first curly bracket.. which - subjectively - makes the ...
1
vote
3answers
95 views

Should I mark what blocks mean in data-* attributes?

I was writing a webpage today with a comment after the start of every major section. Instead of using a comment, which comes with the bulgy <!-- --> syntax, could I instead put this in a data-* ...
0
votes
2answers
167 views

Referencing StackOverflow questions in comments [duplicate]

Often when coding I'll get stuck on a particularly tricky problem and will go about searching for a solution. More often than not this leads me to a StackOverflow question that provides a full or ...
1
vote
3answers
212 views

Is there a need to comment obvious parameters? [duplicate]

Most of the time, when I comment a method, I'll follow this structure. /** * Short description of what the method does * * @param {Type} name. Description of the variable. * * @return {Type}. ...
4
votes
3answers
553 views

Intentionally incorrect use of language features, specifically “ref” in C#, as a hint to colleagues

I recently came across a piece of code something like this (roughly C#): public bool ValidateStuff(ref ArrayList listOfErrors, Stuff thingsToValidate) { if (!thingsToValidate.isValid() ) { ...