Questions about writing comments in code.

learn more… | top users | synonyms

1
vote
3answers
223 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 ...
69
votes
17answers
14k 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 ...
178
votes
16answers
29k 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
979 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
51 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
268 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
452 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
173 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 ...
1
vote
0answers
34 views

First programming job with few resources to learn from [duplicate]

I recently started my first programming job after working for a couple of years developing websites. This new company focuses on PHP and has had only one developer responsible for the code since the ...
17
votes
3answers
3k 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
266 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 ...
1
vote
1answer
538 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 ...
0
votes
1answer
132 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 ...
0
votes
3answers
122 views

Add or leave comment for simple race condition logic? [duplicate]

I'm a huge proponent of removing comments for stuff that should be really clear anyway. Stuff like // remove object from list. A pattern you come across now and than is the preventing of race ...
1
vote
3answers
90 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
127 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
174 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}. ...
1
vote
4answers
427 views

Would comments increase the chance of being fired? [closed]

I have had this burning question for a while. If I have a job and I comment my code well, to the point that anybody can now understand my hard work, would it make me less indispensable to the company? ...
4
votes
3answers
496 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() ) { ...
0
votes
1answer
147 views

if else brackets on same line, best comment style? [closed]

I used to do this: // If the cat is black if ( $catColor == 'black' ) { ... } // Otherwise eat a taco else { ... } But I've more recently started to move toward this style of conditional ...
17
votes
12answers
2k views

Correct comment to put for boolean function arguments that are “false”?

From some open source projects, I gathered the following coding style void someFunction(bool forget); void ourFunction() { someFunction(false /* forget */); } I always have doubt about what ...
1
vote
4answers
488 views

Does a prose to code compiler exist? [closed]

I have seen some horrible code in my time including people virtually duplicating the code in comments // add 4 to x x+=4; // for each i in 0 to 9 for (int i = 0; i < 10; i++) { // multiply x ...
0
votes
0answers
35 views

Changelog in Comments Versus Source Control Log [duplicate]

Until recently, I have worked on a code base which kept change logs both as a table in the header section of each file and as comments in source control. In practice, only the header comments were ...
0
votes
2answers
157 views

How to systematize tagging in code? [closed]

There are several almost standard tags used in comments: FIXME, TODO, BUGBUG. Which other tags do you use and for what? Are there any standards on using them, i.e. format (supplementing with date ...
6
votes
7answers
533 views

Commenting regular expressions

Are there any common practises for commenting the regular expressions: inline comments referring different part of RegEx or general comment for all expression?
4
votes
6answers
2k views

What should I include in my class documentation header

I'm looking for informative class documentation format for my Entity, Business Logic and Data Access classes. I found following two formats from here Format 1 ...
1
vote
3answers
230 views

Commenting strategies in C# & asp.net web api

I've been working on a ASP.NET Web Api 2 project as a learning exercise, and I was wondering what the norm regarding commenting is. I use the Repository / Service Pattern, and everything is very much ...
12
votes
8answers
2k views

Why do most programming languages not nest block comments?

A few do, but not any of the popular ones as far as I know. Is there something bad about nesting comments? I plan to have block comments nest in the (small) language I'm working on, but I would like ...
2
votes
4answers
260 views

Is it normal needing time to understand code I wrote recently [closed]

By recently I mean some weeks ago. I am trying to continue a project I left 2 weeks ago and I need time to understand some functions I wrote (not copied from somewhere) and it takes me time. Normally ...
6
votes
2answers
269 views

What has research shown about the effectiveness of comments?

I have been arguing with a friend about the necessity of comments, and the efficiency of different comment styles. The argument ended quite fast, as we could not find any research - or essay - that ...
5
votes
5answers
1k views

How should I handle exception that *should* never be thrown? [duplicate]

What is the best way to handle errors that shouldn't ever happen? My current way to do this is to throw an exception if the 'thing that shouldn't happen' does happen, like so: /* * Restoring from a ...
2
votes
2answers
239 views

Are multi-line comments a critical facility in a modern language?

I'm trying to convince the designers of a language that multi-line comments with an arbitrary start and end are important, and should be included. Currently there is only a "comment-to-end-of-line" ...
23
votes
5answers
1k views

Beginner's guide to writing comments?

Is there a definitive guide to writing code comments, aimed at budding developers? Ideally, it would cover when comments should (and should not) be used, and what comments should contain. This ...
60
votes
13answers
8k 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()); ...
0
votes
2answers
118 views

Is it a bad practice to cite URLs as references in comments? [closed]

Sometimes I think it's useful to cite a webpage (e.g. Stack Overflow questions) to justify and explain a piece of code. Is this considered bad practice?
3
votes
2answers
726 views

Asterisks in Multi-line comments

Using Visual Studio 2012 with C#, when I write multi-line comments, VS automatically begins each line with an asterisk, like this: /* * * */ I was just curious if this was the case in ...
37
votes
16answers
6k views

Good idea to put bug numbers in a comment in the beginning of the source file? [closed]

Is it a good practice to put bug numbers in the file itself inside a header comment? The comments would look something like this: MODIFIED (MM/DD/YY) abc 01/21/14 - Bug 17452317 - npe in drill ...
1
vote
1answer
93 views

Are there any standards for separating different kinds of comments (explanatory, debug, to-do, etc.)?

For a while now I've been in the habit of differentiating different kinds of comments in my code. //this is an explanatory comment //!this line was commented out for debug purposes, DO NOT SHIP WITH ...
22
votes
21answers
9k views

Self Documenting Code Vs. Commented Code

I had a search but didn't find what I was looking for, please feel free to link me if this question has already being asked. Earlier this month this post was made: ...
0
votes
2answers
421 views

Where to put comments, class declaration or constructor?

For a given class, where should the comments about the purpose of the class go? /// <summary> /// <----------------- describe the class here (1)? /// </summary> public class ...
45
votes
19answers
3k views

Forcing people to read and understand code instead of using comments, function summaries and debuggers? [duplicate]

I am a young programmer (finished computer science university but still under a year of working in the industry) and I recently got a job working on some C code for a decent size web service. Looking ...
0
votes
0answers
598 views

Commenting MVC applications [duplicate]

I've recently realised that my workplace doesn't comment their ASP.NET MVC applications. By 'doesn't document', I mean there is probably 1 line of comment per model/view/controller. No file purpose, ...
-1
votes
1answer
213 views

Is using non-standard single-line comments fine in C? [closed]

I noticed Visual C++ 2010 (my current environment) and XCode both allow non-standard single-line comments in my C programs. Since these are both my target platforms, I assume it's fine to use it? VC++ ...
0
votes
3answers
453 views

Why are there so few comments in C/C++ code? [closed]

I'm a web developer primarily, and I've been learning C/C++ and trying to get involved in some open source projects. Something I find very unusual is the lack of comments in C/C++ source code (I've ...
-2
votes
1answer
100 views

What effect does the utilization of pseudocode and comments have when a software engineer designs software? [closed]

I am a programmer by trade so in my English Class ENC 1102, when we were asked to come up with a discourse community in which we could relate the use of writing skills I thought about pseudocode and ...
2
votes
4answers
428 views

Private comments in git

I need to add a feature to some code in a big project and due to the complexity I find it very helpful to add detailed comments to many lines to keep track of what's happening. This is only for my own ...
22
votes
8answers
2k views

Should comments say WHY the program is doing what it is doing? (opinion on a dictum by the inventor of Forth) [duplicate]

The often provocative Chuck Moore (inventor of the Forth language) gave the following advice[1]: Use comments sparingly! (I bet that's welcome.) Remember that program you looked through - the ...
28
votes
18answers
3k views

Why would a company develop an atmosphere which discourage code comments?

I was taught in university to write comments for our programs. As I write comments, I feel like I have a better organization and understand the programs better. However, I am in a company where most ...
2
votes
2answers
50 views

Infrastructure-related additions in commit comments

For the sake of this question, let's agree on this definition of "good commit message" from here: Your comment should be brief and to the point, describing what was changed and possibly why. and ...
1
vote
1answer
299 views

Best practice for comments above methods in a grails application?

I'm writing a grails application and am not sure what the best practice is with regard to comments outside of method blocks. I've done a bit of research and there seems to be conflicting views on how ...