Questions about writing comments in code.

learn more… | top users | synonyms

3
votes
3answers
166 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
33 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 ...
0
votes
1answer
122 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
116 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
82 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-* ...
1
vote
3answers
168 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
410 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
482 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() ) { ...
162
votes
15answers
27k 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 ...
0
votes
1answer
128 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 ...
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
123 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
195 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 ...
2
votes
4answers
252 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 ...
3
votes
5answers
860 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
236 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" ...
0
votes
2answers
115 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
541 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 ...
1
vote
1answer
92 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 ...
0
votes
2answers
341 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 ...
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 ...
0
votes
0answers
485 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
206 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
444 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
95 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
423 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 ...
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
265 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 ...
10
votes
2answers
370 views

Is spreading code with refactoring comments a good idea?

I am working on a "spaghetti-code" project, and while I am fixing bugs and implementing new features, I also do some refactoring in order to make the code unit-testable. The code is often so tightly ...
27
votes
8answers
1k views

good replacement for commenting out code? [duplicate]

It bothers me to see commented out code and it seems often-times a symptom of developers not being proficient in advanced source control features, but on the other hand source control does not really ...
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 ...
0
votes
2answers
276 views

How to write comments to explain the “why” behind the callback function when the function and parameter names are insufficient for that?

How should I approach writing comments for callback functions? I want to explain the "why" behind the function when the function and parameter names are insufficient to explain what's going on. I ...
17
votes
11answers
1k views

Why are we supposed to use short functions to sectionalize our code? [duplicate]

I've seen an increasing trend in the programming world saying that it is good practice to separate code blocks into their own functions. Obviously, if that code block is reusable, you should do that. ...
70
votes
13answers
4k views

What are examples of comments that tell you why instead of how or what? [closed]

First of all, in this question I'd like to stay away from the polemic on whether source code commenting is good or bad. I'm just trying to understand more clearly what people mean when they talk about ...
5
votes
2answers
174 views

how to pluralize 'special' terms e.g. class names

Quite often I find myself referring in text to objects which have strict naming conventions e.g. Java objects, processes, services. I find myself in a dilemma over how to pluralize these names. It ...
5
votes
3answers
378 views

Why do some opensouce libraries lack comments?

I don't know if this happens to most Opensource libraries, but many of I know and use (for example OpenSSL, Webkit, ...) they all lack comments, or contain very few comments. Not to mention their ...
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 ...
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 ...
2
votes
2answers
252 views

Is it bad to use giant label comments to mark off sections of code? [duplicate]

So I have a fairly big class (nearly 200 lines, so not gigantic). It started to be hard to find parts of the code, so I started making giant comments like the following: ...
1
vote
6answers
904 views

Working in a company that does not comment their code at all? [duplicate]

I work for a small software development house (10~ developers, a few product managers and a few support staff) that sells various products and services to organisations internationally through ...
1
vote
1answer
475 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 ...
16
votes
4answers
2k views

Is the “Gets or sets ..” necessary in XML documentation of properties?

I am looking for a recommendation of a best practice for XML comments in C#. When you create a property, it seems like that the expected XML documentation has the following form: /// <summary> ...
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()); ...
2
votes
2answers
317 views

Leaving “Else” comments

Let's say I have a not-so-intuitive if statement in my code, but only if you're new to the codebase: def set_markets(markets=None): """ Will accept 'all' as markets to set all markets on. ...
-1
votes
1answer
271 views

Is there a code tag to indicate “need improvement” on code comments? [closed]

TODO indicates "task to be completed", FIXME to be fixed etc. Is there a code tag to indicate "need improvement" on code comments?
1
vote
2answers
130 views

@Deprecated as of version x.y in JavaDoc

This question & its answers are useful but not sufficient for my problem. My Question is if I want to add a javadoc as @Deprecated As of version x.y, replaced by {@link SomeClass} in my current ...
161
votes
23answers
14k 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 ...
6
votes
7answers
527 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?
5
votes
7answers
746 views

In what stage of development should comments be written?

I'm a student working an internship at a larger company, writing small business apps in C#. I've noticed that I don't comment my code as I write it. Rather, I comment my code when I'm in the ...
8
votes
4answers
778 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 ...