Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
There is an on-going minor debate where I work about the efficacy of comments within code. One of the leads instructed his developers not to use comments as they are too "old fashioned", and a couple of other developers indicated that they never use comments because they feel all they do is clutter up the code.
I have always pretty much adhered to the practice that I comment the top of every file with a basic comment block, comment each method/class/etc definition, and then I comment any place in the code where I think I might come back in 6 months and think to myself, "WTF".
Clearly this is subjective, but I'm curious to know if anyone has any really good arguments or experiences for one way or the other.
I'll just point you to Jeff Atwood's wonderful post on the subject, which hits the nail right on the head.
In all my career, I have never come across that wonderful beast "self-documenting code". Maybe I've just been unlucky, but I'm beginning to suspect it doesn't actually exist.
Every once in a while I run across code that is so elegantly partitioned, has such compellingly obvious method, field and variable names that everything I need to know is obvious from the code.
In the general case, only really great code gurus write such code. The rest of us cobble together something that works.
If you're a really great code guru, don't bother sullying your divine code with superfluous comments.
If you barely know what you're doing, be careful to document your blundering attempts so others can try to salvage the mess.
If you're average (and most of us are, sort of by definition) then leave some hints in comments for yourself and others to make things easier at maintenance time, but don't insult anyone's intelligence and waste space by documenting the REALLY obvious. Ideally, your comments should describe your code at a meta-level, indicating not what you're doing but why. Also how, if you're doing something unusual or tricky.
"One of the leads instructed his developers not to use comments as they are too "old fashioned", and a couple of other developers indicated that they never use comments because they feel all they do is clutter up the code."
If I ever heard a developer I was working with talk like this, I would correct them. If I didn't have the necessary rank to correct them, I would leave the job.
Very clearly written code, with good identifiers -- the stuff sometimes referred to as 'self-documenting' -- does a fine job of illustrating what the code is doing. That's fine as far as it goes. The job of the comments is to explain why.
This topic tends to be discussed a lot, but here are my US$0.02 on the subject:
I would rather see too many comments than not enough. Failing at anything, you can always delete superfluous comments from the code; however, you can not derive meaning from them if there are none there to begin with.
I've heard some developers argue that other developers that "over document" (definitions of this vary by person) their code are not good developers. While saying that you are updating a counter might be a sign that you don't know what you are doing, having a clear guide to some of the business logic sitting there in the middle of the method you are working on can be quite useful.
While there are some excellent developers out there that can write extremely clear code that doesn't require comments, most developers aren't that good or they spend more time writing the code to be self documenting than they would if they had just included a couple comments.
You don't know the skill level of the next person to read your code and if the language constructs you are using might be confusing it is usually a good idea to include a comment that someone can use to Google a tutorial with.
The problem with comments is that they tend to stay long after the code that was commented has changed or even been deleted.
As a rule of thumb I'd only comment public API and difficult to understand algorithms.
Don't use comments to explain what you did - that's what the code is for, use comments to explain why you did it.
Diomidis Spinellis just wrote a nice column for IEEE column (quoted on his blog), outlining the problem, and a few solutions:
When commenting, we’re always a couple
of keystrokes away from disaster:
restating the code’s function in
English. And that’s when problems
start.
One should write comment before the code or before the function so that next time looking at the function he/she can know immediately what was the purpose of that code.
It is happened to me many times that I write the code and then forgot the purpose of that. so, I make habit of writing comment before code.
What I'd like to see in the comments is an explanation why a method that is obvious and much simpler than the method used in the code doesn't work.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
If you are given a large n-tier project (.NET) with 15,000 lines of code written in "Spanish" (variables, tables, classes names etc) that requires feature addition and bug fixing, what would be your strategy to work on it?
Converting the whole project to English(Google Translation or other tools) names does not seem to be a good options as it will be time consuming
Hire a developer who knows "Spanish" or a translator
EDIT: The developers who wrote the original software does not understand English so they are not useful in this case.
Attempt to work on it as it is without translating anything. If it doesn't work, start translating it on-demand, only pieces that are relevant to you.
A dictionary can get you quite far already. You can translate code elements on your own. Naturally, don't add any more pieces to the puzzle. What you add should be in English.
I would also notify the customer that due to the code being written against common sense and best practices in non-English (and even unfamiliar to you language) there will be a delivery delay. Blame on the original creator of the novel.
Unless this is The Project From Hell, there should be far fewer than 15000 variables and methods in your code. My on-the-cheap suggestion would be for you to extract a cross-reference list of variable names as found in your program, hire a quick cheap Spanophone to translate those names for you, and then keep the translation list handy as you and your teammates code.
It's handy to have an idea of what is meant by a variable name, but it's not essential. I spent 20 years writing programs with only 4 significant characters in the variable name.
It's subjective, but my personal opinion is Option B) Hire a developer who can speak spanish - primarily because all the commenting will likely to be in spanish and if the commenting has been done well - it will have valuable information within that should not be ignored / lost.
A translator might not be able to understand the terms within the comments / code and a translation by a non programmer could go bad.
Best option would be to get in touch with the guys who wrote the darn thing...if possible at all. Second best, a developer who knows Spanish.
Translate your classes first. Then you should be able to keep track of instances by their type.
Sorry mostly questions.....
Is the customer a Spanish speaker? If so the software should be written by a Spanish programmer. As the cost of communicating with the customer is a lot less if the programmer understands the customer.
If the customers is not Spanish, why was a Spanish programmer used at all?
Was the Spanish programmer chosen to save money?
If so, is the software worth keeping at all?
How can you tell how good the code is if you can’t read Spanish?
I think the translation should be done as needed on demand, e.g
All new code should be in “English”.
All methods that are changed should be in “English”
All class/methods the new code uses should have English names and summary comments.
The names and comments on all unit tests for class/methods with English names should be in English
Missing unit tests should be written for any class/method when it is not clear what the spec is. (So as to check the translation of the comments into English.)
I think a willing English programmer will be able to use Google translate to do the above, however as with any new source code base, the programme will have to spend a long timer really understanding what each class/method does before using it.
An English programmer that knows some Spanish would be able to do it quicker. However don’t use a Spanish programmer, as you always want a translator translating into their native language.
First step, and this is true when you inherit a legacy code base whether it's in your native tongue or not, is to set up regression tests based on "known good" output, and begin writing more tests as you go, for the changes you make.
Quite possibly, given the relatively small size of the code base, you will fairly shortly start to understand what various routines are doing, and may be capable of beginning the translation effort yourself, maybe supplemented by automated translation.
This assumes you understand the problem domain, and that the original code was written professionally.. although if it were, you'd already have tests, wouldn't you? You don't mention whether that's the case.
Doing anything here without regression tests is foolhardy. Doing it with tests, you may find the whole task relatively manageable and don't need a serious translation effort. Definitely respect the other suggestions to do this incrementally too.
I can get all of methods, fields, annotations and etc. with reflection methods and etc. to export excel or etc. Then I can send this excel file to spanish translator. After translated, i can convert all of project codes by reference which is translated excel file by text processor applications (find / change etc.)
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
G'day,
Inspired by a comment I made in my answer to this question on commenting Perl regexps I was wondering the following.
When you are working on older, old, bloody ancient, code do you update comments that are out of sync with the code or do you just update the code and ignore the comments that are already "miles out" from the reality of the current code?
I guess basically approaching things from the "broken window" syndrome?
BWS basically says that people just say "stuff it" and don't take care to fix errors that are there if they see that people, already involved with the system in question, didn't care enough to fix these sorts of things. A totally pervasive mind set IMHO!
I'd be interested to see what other people "at the coalface" do.
cheers,
I will absolutely fix bad comments.
Sometimes it is just to delete them so that they don't mislead.
Better still, I prefer to refactor the code so the comments are not necessary - self documenting code is better than comments because it can't get out of date.
Recently I started following more of Uncle Bob's Clean Code advices and I'm trying to transform comments into functions that enclose (extract) the commented code in a function that is at least as meaningful as the comment it replaces.
I always try to update them if I can, or at the very least add a note to the effect that they might be wrong. It's a worthwhile investment of a small amount of time.
The other thing I always do is add any relevant bug numbers, and what effect those edits had - that's always useful to see further down the line.
If the comment is necessary, I'll update it, otherwise I'll attempt to change the code to the point where I can just outright delete the comment and let the code document itself.
When i find useless GhostDoc-generated comments, i sometimes just delete them:
What's the purpose of these comments?
/// <summary>
/// Saves the form properties.
/// </summary>
/// <param name="form">The form.</param>
/// <param name="propertyNames">The property names.</param>
void SaveFormProperties(Form form, string[] propertyNames);
As a fairly fresh programmer, I don't really work much on older code as much as my own, but I try to go back every once in a while to ensure my own comments are mildly close to the truth. It makes no sense to leave comments that don't properly describe the function of the code.
That said if you're in a hurry it makes no sense to waste too much time updating comments. Adding one to the effect of "This is out of date" solves the problem of retaining navigation without leaving it ambiguous as to how accurate it is.
If your documentation is being generated from the comments (I highly recommend this anyway) then yes, I keep the comments in meticulous synch with the code.
I immediately fix the comments if I see a problem, and probably note down what it would take to improve the code.
If I then get hit by a bus, the code is all the better for my quick, pointed attention.
Then, if I have time, I'll sort the code itself out (fixing it usually requires time consuming regression testing). If not, I'll leave it for another day, but at least I'll know what the problem is right away when I do have time to come back to it.
Comments are oftten really useful for telling any future maintainers or programmers either what the code is doing or why it is doing it that way.
If you change the code without updating the comments, at best it's going to be confusing, if not downright misleading.
I strive to follow the Boy Scout Rule and leave the code cleaner than I found it. I will look to update the comment or refactor the code to obviate the need for the comment. I find that it is generally better not to have a comment at all than it is to have an incorrect comment.
I would fix the comments.
Why not fix any problem you can? If you understand the code you're working on, the comments should be the easiest fixes of all. Obviously if you've taken the trouble to delve into it the code should all be left better than you found it.
I would even posit that in groups where multiple people will be touching the code the comments could be considered just as important as the code itself. Without it the communication of ideas is broken down.
In practice I probably don't comment as well as I should. It's hard to admit that you or someone else will probably be digging around in your "masterpiece" later.
I would fix the comments. I saw some answers said they would rewrite the code if the comments were out of date. It seems absurd to me to rewrite working code just because the comments are bad. That kind behavior might even get you fired if your work is important enough.
I always fix the comments - primarily because I am usually the one who works on a piece of code. It may be an OCD like thing for me, but I just like code that I am working on to look nice - good variable names, formatting (not an issue now with modern IDE's), and comments.
I don't believe code can be "refactored to the point it is self-documenting". It can be refactored to the point where only comments for functions, procedures, member variables, classes etc. are needed, because each function call is only 1-5 lines each. Coming from a Lisp background I like to program through decomposition - much simpler, testable, and easier to prove correct.
If the project is under version control (and it should be nowadays, but you never know) and there's a huge hunk of out-of-date comments, I delete the hunk and leave a new comment to the effect that I've deleted a hunk of old comments that no longer seemed illuminating, and I submit with a note that I've deleted out-of-date comments.
Eventually, I'll remove the comment that mentions the deletion, or replace it with comments that apply to the new code.
However, here's the downside to changing old, supposedly meaningless comments in a system that's being maintained by a group of programmers:
The comments aren't acting as comments anymore! They are acting as landmarks for programmers familiar with the code. They're landmark comments as opposed to explanatory comments.
Programmers may actually be searching on keywords in landmark comments to navigate the file.
If you remove landmark comments, or even change them, you may drastically slow programmers who are using them to navigate the file. You're messing with the mental maps of people who have a long relationship with the code, and you'll do more damage than good. The brain's a funny thing. It may be much easier to remember a word or phrase in a funky comment than the name of a method.
It seems to me that if the comments are dreadfully out-of-date with the code, you should learn why. It seems incredibly presumptive to assume that the other programmers don't care about the code. Maybe they do, maybe they don't. If you're taking over the files from a guy who left, and you have clear ownership, dig in! If you're the new guy amongst a bunch of guys who've been working on the code for 20 years, and there's other evidence that they do care about the code, maybe you're missing something.
This is similar to the question of reformatting--changing spacing, altering where the opening braces go, etc. And much depends on ownership. Are you going to be in a file 20 times as much as the guy next to you? Or 1/20th as often? If it's the latter, do you really want to disorient him?
So make sure that's not what you're doing, or tomorrow you may hear someone yelling, "Where the hell is that function?"
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 14 years ago.
How do you explain your team mates the importance of commenting the code they write? I know some coders who write episodic comments while others leave a lot to be expected, what do you expect when you read comments?
There are some minimums:
All functions and classes should be commented
Try/Catch and exception handling is better to be commented
Constants hard coded in the code should be definitely
dummy objects and dummy classes, as well as TO-DO parts should be commented
When you get a code from a URL, the address should be cited in the comments for further consideration and copyright infringement problems
Also commits to the version control system should be well commented
Although comments should be kept to minimum, there is no need to comment a for loop definition when it is obvious,
I usually set ground rules for my programmers, they stick to it when it is well defined
The best comments are always concise, in a few words. It should say what's not obvious in the code. I see allot of people making obvious and therefore useless comments like:
if x==0 //if x equals 0 then...
oh really?! This is only "polluting" the code, because unless you're learning how to program, its pretty useless.
Even if the code is only yours, you should write comments as if you were about to share it with another programmer that is completely unaware of it. That way you make sure that you will always understand it, and in long term if somebody comes along and picks that code up, that person will be able to understand it and extend/use it.
I see comments as a boost of reusability. And I expect, like every other programmer, to fully understand a block of code with a single, simple and concise comment.
Write comments when you're writing code that's not intuitive. There's really no reason for commenting a method that just iterates an array, but when you fix a bug or have to hack something together to get around an issue, it's good to have a comment so you can quickly understand that code 6 months later (and not accidently undo it).
What do you mean by commenting code?
The actual code, or the function headers?
If you're actually talking about the code, it's a lost cause. You need to get them to write readable code and to break it into meaningful chunks. Commenting bad code doesn't make it into good code, it just leaves an inconsistent mess.
As for header documentation, you have to get them to capture the important things (e.g., surprises, directives) and compromise about trivial things (listing all parameters, repeating what the signature does). People hate documenting functions because most of the effort is spent writing trivial text that almost insults your intelligence (e.g., on getHandleToFile(), "this gets a handle to the file"). Since there are actually a lot less important details than one would expect, they'd be pleasantly surprised and would be more likely to invest the effort in those specific situations.
I think if you are writing code that others may someday have to follow, then it is prudent to leave good comments about what things are doing. If you are just writing something for yourself, the tendency is strong to leave minimal or none at all. That being said, I have had the "not so luxury" of having to go back to code I wrote 8 years ago and didn't comment adequately, in a language I don't use anymore (class ASP) and I can tell you, I wish I had left more comments!
I try to comment most of my public methods and classes, and in those comments you can read what the method does, what the meaning of the parameters is, and, if applicable, what the output will be.
I also sometimes put comments inside my methods, but, there I do not comment what I'm doing, but why I am doing it like that.
if the language you are writing in is not human readable, i suggest very granular method and procedure level comments.
if the language you are writing is human readable (C#, VB, etc..) i suggest that you use somewhat detailed comments at the method level and minimal comments at the procedure level.
Include comments for document generation on methods and classes.
Don't comment every line.
If you are doing something expected or that is not obvious from the code, explain why in comments.
The most important thing to do in commenting is to tell the truth. The number of times I've been investigating a bug only to find a section of code that is "less than obvious" along with a comment that says it's supposed to do the opposite to what it is doing. Who wins? You decide...
On a related note, any comment that is longer than the section it is documenting is normally too long.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 months ago.
Improve this question
I have seen the other questions but I am still not satisfied with the way this subject is covered.
I would like to extract a distiled list of things to check on comments at a code inspection.
I am sure people will say things that will just cancel each other. But hey, maybe we can build a list for each camp. For those who don't comment at all the list will just be very short :)
I have one simple rule about commenting: Your code should tell the story of what you are doing; your comments should tell the story of why you are doing it.
This way, I make sure that whoever inherits my code will be able to understand the intent behind the code.
I comment public or protected functions with meta-comments, and usually hit the private functions if I remember.
I comment why any sufficiently complex code block exists (judgment call). The why is the important part.
I comment if I write code that I think is not optimal but I leave it in because I cannot figure out a smarter way or I know I will be refactoring later.
I comment to remind myself or others of missing functionality or upcoming requirements code not present in the code (TODO, etc).
I comment to explain complex business rules related to a class or chunk of code. I have been known to write several paragraphs to make sure the next guy/gal knows why I wrote a hundred line class.
If a comment is out of date (does not match the code), delete it or update it. Never leave an inaccurate comment in place.
Documentation is like sex; when it's
good, it's very, very good, and when
it's bad, it's better than nothing
Write readable code that is self-explanatory as much as possible. Add comments whenever you have to write code that is too complex to understand at a glance. Also add comments to describe the business purpose behind code that you write, to make it easier to maintain/refactor it in the future.
The comments you write can be revealing about the quality of your code. Countless times I've removed comments in my code to replace them with better, clearer code. For this I follow a couple of anti-commenting rules:
If your comment merely explains a line of code, you should either let that line of code speak for itself or split it up into simpler components.
If your comment explains a block of code within a function, you should probably be explaining a new function instead.
Those are really the same rule repeated for two different contexts.
The other, more normal rules I follow are:
When using a dynamically-typed language, document the expectations that important functions make about their arguments, as well as the expectations callers can make about the return values. Important functions are those that will ever have non-local callers.
When your logic is dictated by the behavior of another component, it's good to document what your understanding and expectations of that component are.
When implementing an RFC or other protocol specification, comment state machines / event handlers / etc with the section of the spec they correspond to. Make sure to list the version or date of the spec, in case it is revised later.
I usually comment a method before I write it. I'll write a line or two of comments for each step I need to take within the function, and then I write the code between the comments. When I'm done, the code is already commented.
The great part about that is that it's commented before I write the code, so there are not unreasonable assumptions about previous knowledge in the comments; I, myself, knew nothing about my code when I wrote them. This means that they tend to be easy to understand, as they should be.
There are no hard rules - hard rules lead to dogma and people generally follow dogma when they're not smart enough to think for themselves.
The guidelines I follow:
1/ Comments tell what is being done, code tells how it's being done - don't duplicate your effort.
2/ Comments should refer to blocks of code, not each line. That includes comments that explain whole files, whole functions or just a complicated snippet of code.
3/ If I think I'd come back in a year and not understand the code/comment combination then my comments aren't good enough yet.
A great rule for comments: if you're reading through code trying to figure something out, and a comment somewhere would have given you the answer, put it there when you know the answer.
Only spend that time investigating once.
Eventually you will know as you write the places that you need to leave guidance, and the places that are sufficiently obvious to stand alone. Until then, you'll spend time trawling through your code trying to figure out why you did something :)
I document every class, every function, every variable within a class. Simple DocBlocks are the way forward.
I'll generally write these docblocks more for automated API documentation than anything else...
For example, the first section of one of my PHP classes
/**
* Class to clean variables
*
* #package Majyk
* #author Martin Meredith <martin#sourceguru.net>
* #licence GPL (v2 or later)
* #copyright Copyright (c) 2008 Martin Meredith <martin#sourceguru.net>
* #version 0.1
*/
class Majyk_Filter
{
/**
* Class Constants for Cleaning Types
*/
const Integer = 1;
const PositiveInteger = 2;
const String = 3;
const NoHTML = 4;
const DBEscapeString = 5;
const NotNegativeInteger = 6;
/**
* Do the cleaning
*
* #param integer Type of Cleaning (as defined by constants)
* #param mixed Value to be cleaned
*
* #return mixed Cleaned Variable
*
*/
But then, I'll also sometimes document significant code (from my init.php
// Register the Auto-Loader
spl_autoload_register("majyk_autoload");
// Add an Exception Handler.
set_exception_handler(array('Majyk_ExceptionHandler', 'handle_exception'));
// Turn Errors into Exceptions
set_error_handler(array('Majyk_ExceptionHandler', 'error_to_exception'), E_ALL);
// Add the generic Auto-Loader to the auto-loader stack
spl_autoload_register("spl_autoload");
And, if it's not self explanatory why something does something in a certain way, I'll comment that
The only guaranteed place I leave comments: TODO sections. The best place to keep track of things that need reworking is right there in the code.
I create a comment block at the beginning of my code, listing the purpose of the program, the date it was created, any license/copyright info (like GPL), and the version history.
I often comment my imports if it's not obvious why they are being imported, especially if the overall program doesn't appear to need the imports.
I add a docstring to each class, method, or function, describing what the purpose of that block is and any additional information I think is necessary.
I usually have a demarcation line for sections that are related, e.g. widget creation, variables, etc. Since I use SPE for my programming environment, it automatically highlights these sections, making navigation easier.
I add TODO comments as reminders while I'm coding. It's a good way to remind myself to refactor the code once it's verified to work correctly.
Finally, I comment individual lines that may need some clarification or otherwise need some metadata for myself in the future or other programmers.
Personally, I hate looking at code and trying to figure out what it's supposed to do. If someone could just write a simple sentence to explain it, life is easier. Self-documenting code is a misnomer, in my book.
I focus on the why. Because the what is often easy readable.
TODO's are also great, they save a lot of time.
And i document interfaces (for example file formats).
A really important thing to check for when you are checking header documentation (or whatever you call the block preceding the method declaration) is that directives and caveats are easy to spot.
Directives are any "do" or "don't do" instructions that affect the client: don't call from the UI thread, don't use in performance critical code, call X before Y, release return value after use, etc.
Caveats are anything that could be a nasty surprise: remaining action items, known assumptions and limitations, etc.
When you focus on a method that you are writing and inspecting, you'll see everything. When a programmer is using your method and thirty others in an hour, you can't count on a thorough read. I can send you research data on that if you're interested.
Pre-ambles only; state a class's Single Responsibility, any notes or comments, and change log. As for methods, if any method needs substantial commenting, it is time to refactor.
When you're writing comments, stop, reflect and ask yourself if you can change the code so that the comments aren't needed. Could you change some variable, class or method names to make things clearer? Would some asserts or other error checks codify your intentions or expectations? Could you split some long sections of code into clearly named methods or functions? Comments are often a reflection of our inability to write (a-hem, code) clearly. It's not always easy to write clearly with computer languages but take some time to try... because code never lies.
P.S. The fact that you use quotes around "hard rules" is telling. Rules that aren't enforced aren't "hard rules" and the only rules that are enforced are in code.
I add 1 comment to a block of code that summarizes what I am doing. This helps people who are looking for specific functionality or section of code.
I comment any complex algorithm, or process, that can't be figured out at first glance.
I sign my code.
In my opinion, TODO/TBD/FIXME etc. are ok to have in code which is currently being worked on, but when you see code which hasn't been touched in 5 years and is full of them, you realize that it's a pretty lousy way of making sure that things get fixed. In short, TODO notes in comments tend to stay there. Better to use a bugtracker if you have things which need to be fixed at some point.
Hudson (CI server) has a great plugin which scans for TODOs and notes how many there are in your code. You can even set thresholds causing the build to be classified as unstable if there are too many of them.
My favorite rule-of-thumb regarding comments is: if the code and the comments disagree, then both are likely incorrect
We wrote an article on comments (actually, I've done several) here:
http://agileinaflash.blogspot.com/2009/04/rules-for-commenting.html
It's really simple: Comments are written to tell you what the code cannot.
This results in a simple process:
- Write any comment you want at first.
- Improve the code so that the comment becomes redundant
- Delete the now-redundant comment.
- Only commit code that has no redundant comments
I'm writing a Medium article in which I will present this rule: when you commit changes to a repository, each comment must be one of these three types:
A license header at the top
A documentation comment (e.g., Javadoc), or
A TODO comment.
The last type should not be permanent. Either the thing gets done and the TODO comment is deleted, or we decide the task is not necessary and the TODO comment gets deleted.