Questions about writing comments in code.
14
votes
12answers
1k 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
votes
1answer
173 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 ...
16
votes
11answers
951 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
3k 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
161 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 ...
4
votes
3answers
300 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 ...
41
votes
19answers
2k 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 ...
15
votes
3answers
1k 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
5answers
287 views
Use stackoverflow link as replacement for source code comment [closed]
I found out nowadays, instead of writing comment for source code which requires clarification, most of the time there is just a link to stackoverflow Q&A. Does your source code also having such ...
2
votes
2answers
227 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
590 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 ...
0
votes
1answer
151 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 ...
15
votes
4answers
735 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>
...
49
votes
13answers
6k 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
313 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.
...
