Questions tagged [comments]

Questions about writing comments in code.

Filter by
Sorted by
Tagged with
-1 votes
0 answers
24 views

Good / Better / Best Practices with JS Comments [duplicate]

Looking for some tips with commenting on JS files, trying to improve process where I can. I maintain and update a business application as a sole developer. It is widely used but not publicly ...
user avatar
8 votes
4 answers
526 views

How to document alternative code I considered but didn't go with due to performance?

I write code in R, and often find myself attempting to optimize the code for better performance. In a given script that tackles a specific problem, I test different code alternatives and compare them ...
user avatar
  • 199
1 vote
5 answers
170 views

How to refer to an e-mail in source code comment

Sometimes there are elaborate discussions about a subject, and while finally developing the program, you want to refer to a mail ... but then people still continue mailing about the subject, so the ...
user avatar
  • 1,633
2 votes
3 answers
316 views

Versioning a function/method

While this might seem more like a piece of an easy task to others, it's honestly not easy for me. At this stage, I find myself wandering how best to version my functions/methods. What does this mean? ...
user avatar
  • 141
1 vote
4 answers
654 views

Is it good practice to put comment headers into each file?

I have an Unity project with countless of C# script files and I'm working on it solely. Although nobody else is working on it, I'm aware that some form of code documentation is crucial for my future ...
user avatar
  • 23
49 votes
6 answers
12k views

Is a comment aligned with the element being commented a good practice?

I am a home, amateur developer for 25 years and I just had a bright idea regarding comments. Like all such novel bright ideas, someone has probably already done it and there is probably a consensus on ...
user avatar
  • 1,555
2 votes
1 answer
146 views

Are there established approaches to providing informal proofs of properties a function or system has?

I have asked about the more nebulous 'system' and functions in general, but to explain my question let me just consider a pure function. I think of pure functions as lemma/theorems/what have you. ...
user avatar
4 votes
5 answers
216 views

Approaches for comment duplication

For code, we know approaches like DRY and we tend to extract common functionality. What approaches are recommended for comments? Perhaps it's a really open question, so I'm going to go with my ...
user avatar
  • 161
0 votes
2 answers
121 views

Should I declare motivation when commenting? [duplicate]

When commenting code, which of the two approaches considered good practice? Explain the content of the code, "translate" it to human - readable language, but not provide any explanation ...
user avatar
  • 117
4 votes
5 answers
222 views

Dealing with unwanted usages of a function

I am writing a function that I would not like to get called given a certain context and am wondering how best to convey that to possible users of the function. Assume, for exemplification, I am ...
user avatar
1 vote
0 answers
48 views

What to put in which kind of comment in ClearCase?

I'm used to comments in Git and Mercurial repositories: Commit comments, which may involve multiple files over the whole repository - has a comment. Commits without comments are possible, but rare (...
user avatar
  • 2,366
67 votes
13 answers
17k views

How to avoid comments about one line of code for cleanliness

I'm trying to clean up some of my code using some best practices, and read that comments are almost always a bad idea for future maintainability. I've managed to get rid of most of them by refactoring ...
user avatar
  • 1,477
39 votes
9 answers
9k views

Is there a method for differentiating informative comments from commented out code?

Throughout the course of programming, you will end up with some comments that explain code and some comments that are removing code: // A concise description const a = Boolean(obj); //b = false; Is ...
user avatar
  • 587
4 votes
3 answers
2k views

How to deal with long URLs in comments that exceed the 80 characters limit?

I generally try to adhere to the 80 character limit for each line of code to satisfy my colleagues, to satisfy the linting tools, and to maintain an image of professionalism when random people look at ...
user avatar
  • 151
1 vote
2 answers
456 views

Python method docstring: to use or not to use Args: Returns:

Default docstring from PyCharm automatically creates template with Args: and Returns: sections. However I have observed that this prompts people to say obvious things, frequently just stating the ...
user avatar
  • 149
3 votes
1 answer
189 views

How should I document a method's computational complexity in the code?

I am currently working on a project that has very little documentation overall. The team is working to change that. I am doing my part, by adding xml comments to the methods I make and the ones I edit,...
user avatar
  • 141
9 votes
1 answer
990 views

What does "TILT" mean in a comment?

I'm reading Clean Code by Robert C. Martin, and the phrase TILT inexplicably appears in some code samples. Example (it's in Java, by the way): ... public String errorMessage() { switch (...
user avatar
  • 201
2 votes
1 answer
99 views

Are file summary comments a good way of knowing what each file does?

I want to know if including a file summary comment at the beginning of each file is a good way of knowing what each file does or is there a better way.
user avatar
  • 131
3 votes
1 answer
403 views

Alternative for commented out code that will be used later

I had to implement a module that after completed, the client suddenly asked that for a while it would not need to be displayed, so I was told to comment it out (since we probably will use it later) ...
user avatar
31 votes
6 answers
14k views

Why is it wrong to comment out code and then gradually remove it to keep track of what I've already done and what remains to be done?

Whenever I find out that a large portion of my code needs to be changed, either because it is incorrect or because it needs to be adapted to major architectural changes necessited by other reasons, ...
user avatar
  • 3,307
-1 votes
2 answers
733 views

Is it good practice to add comments above generated fields?

Every time I let Eclipse generate a field (most often a serial version UID), it adds a comment above it. Example: /** * */ private static final long serialVersionUID = 6347144762354188381L; This ...
user avatar
  • 300
0 votes
1 answer
849 views

Should I add XML comments in DTO models or entity models

I have 2 models, DTOs and database models (entities) that map to the database. I usually put XML comments above the properties to describe what are they for. class MyEntity { /// <summary> ...
user avatar
  • 1,401
1 vote
2 answers
124 views

Links to documentation in comments? [duplicate]

I sometimes put a link to the site where I copied a chunk of code from in case I forget what it does. Is this a bad practice? Should I copy the explanation from the site instead of linking to it?
user avatar
4 votes
3 answers
3k views

How do you denote a variable in a comment?

Let's say I have the following function in Python: def foo(one, two): return one + two And I want to document it with "adds one to two". However, this is confusing, because I could just mean ...
user avatar
  • 657
6 votes
5 answers
1k views

Documenting design decisions in code comments?

How can I best document a code design decision in my source code? Should I just add a massive comment at a point I feel is right? Or should I just create a separate file? This issue is important for ...
user avatar
4 votes
3 answers
3k views

Should //given //when and //then comments be included in unit tests?

I've joined a new team of great colleagues and a difference of opinion has come up concerning including //given //when and //then comment blocks in unit tests. For example public void ...
user avatar
  • 275
99 votes
12 answers
16k views

My client wants 25% of comments in my current project, how to react? [closed]

junior developer here. I am currently working alone on a web application for a big client of my company. I started last month. The client wants at least 25% of comments in each of its software ...
user avatar
  • 553
9 votes
5 answers
1k views

Is it generally helpful to include JIRA issues in code comments?

Once in a while, I leave comments like # We only need to use the following for V4 of the computation. # See APIPROJ-14 for details. or # We only need to use the following for V4 of the computation....
user avatar
  • 327
13 votes
3 answers
2k views

Are docblock typehints redundant when using strict typing

I have a quite large private codebase which has evolved for about ten years now. I'm not using phpDocumentor but since using docblock sections has become quite the standard in open source projects I ...
user avatar
  • 241
4 votes
4 answers
456 views

Which is better, one central detailed comment, or several smaller ones?

To restate the question: Which is better, one central detailed comment, or several smaller "sprinkles"? Bear with me while I set up the scene: I've got this function for popping a value from a queue ...
user avatar
3 votes
2 answers
1k views

Additional spacing before an inline comment [closed]

Early on in my career I was advised to add additional spacing between source code and an inline comment, like so: de_cologne = (i == 4711 # 1 and j == 1799) # 2 Note the two spaces. ...
user avatar
1 vote
1 answer
173 views

Are comments at the top of a source file a bad idea? [duplicate]

I use Xcode to edit my source files, and typically a file will look like this // // Queue.swift // SomeCompany // // Created by Someone (Job Title) on 26/06/2017. // Copyright © 2017 SomeCompany. ...
user avatar
1 vote
1 answer
93 views

Making control flow explicit through printing instead of using comments?

I would have the opinion and good practices in script programming about using print statements to materialize the control flow (I usually use an anchor mark, then the name of the function just entered,...
user avatar
-2 votes
2 answers
292 views

Is it ideal to put code comments in an official release?

I will release a program (not Alpha/Beta/Testing versions). Should I remove the comments in the code? I have some comments that I added to make the code less confusing to me, but since the program ...
user avatar
2 votes
1 answer
1k views

Describing JS program flow in @fileoverview

I have to edit other people's JavaScript code. The code usually loads some data from a Web API, generates a table, places it into the HTML page, and attaches some event handlers. Due to the async ...
user avatar
0 votes
1 answer
67 views

Should requirement/issue number/code be included in the comments of the source code? [duplicate]

I am working on a number of maintenance projects and I always include requirement/issue number/code in the the comments whenever I am adding or changing code. In such way I provide traceability from ...
user avatar
  • 1,001
6 votes
1 answer
2k views

Style: line length and wrapping of comments in JavaScript [closed]

I'm fine with staying under 80 characters per line for code (even if some consider that limit outdated), but I'm split (no pun intended) when it comes to splitting comments over multiple lines, versus ...
user avatar
5 votes
3 answers
443 views

How to avoid falling into the trap of not commenting code? [duplicate]

I've been working on a project for about a month now. I am extremely familiar with the code and understand it to the extent where I feel that it is so easy to understand, that most methods don't need ...
user avatar
51 votes
7 answers
9k views

TODO comments with deadlines?

Background I'm working in a team that's looking to implement zero-downtime deployments. We're planning on using a blue/green deployment strategy in order to achieve this. One of the things I'm ...
user avatar
1 vote
1 answer
87 views

Should I doxygenate implementation files in a library of mine, in addition to the headers?

I'm in the process of writing Doxygen comments for this library of mine; it's a header-mostly C++ library, but it does have some code which gets linked rather than included. For that code, which has ....
user avatar
  • 2,366
6 votes
1 answer
1k views

Abuse of XML comments to keep comments up-to-date (in C#)

Problem: Comments deteriorate when renaming a variable/class/method/etc in Visual Studio. Occurrences of said symbol in comments do not get updated by refactoring (no surprise, how could VS know). ...
user avatar
  • 169
4 votes
3 answers
161 views

Is the following comment clear: "Until contested" [closed]

Suppose that you see the following pattern in code: function foo() { ... var someFlag = false; // Until contested for/while/if () { ... // Possibly deeply nested in some ...
user avatar
  • 51
3 votes
2 answers
6k views

What is the difference (if any) between REM statements and comments?

I have recently come across the term REM statement and wondered, is it synonymous with comment?
user avatar
-4 votes
2 answers
703 views

What to do with old code? [duplicate]

Often I change code but I don't know if I might need the old one, I can leave it under comment but then I find myself with lots of green lines while I hardly can read the real code. Thanks.
user avatar
0 votes
6 answers
244 views

Using HTML id or class instead of comments

I have two elements inside a container. I don't need to give the two inner elements any id or class since they require no CSS or JS references. Is giving them an id just for the purposes of ...
user avatar
  • 201
148 votes
17 answers
42k views

Coding standard for clarity: comment every line of code?

I've worked in shops that produce life critical software and I've dealt with commenting rules that were meant to keep the code readable and potentially save lives. In my experience though the ...
user avatar
13 votes
1 answer
357 views

Introducing additional local variables as comment replacement

Is it good style to use additional, technically superfluous, local variables to describe what's happening? For example: bool easyUnderstandableIsTrue = (/* rather cryptic boolean expessions */); if(...
user avatar
8 votes
3 answers
2k views

"Comment everything the right way" and "Instead of writing comments, write more readable code." - Both valid strategies?

When trying to learn about proper comment practices, I found a lot of conflicting opinions, and it's obviously a very subjective topic. So I'm not going to ask "Should I comment, or should I not?" ...
user avatar
2 votes
3 answers
2k views

Is there a way to comment a source file using a separate file?

I'm using a large and complex library including R and C++ code, available online via a subversion repository. Trying to figure out how it works I took a bunch of notes in the source code itself, in ...
user avatar
  • 129
3 votes
2 answers
204 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 ...
user avatar
  • 1,673