• Ron Fox (google)

    Wonder what the frist backup is named.

  • quackers (unregistered)

    TRWTF is listening to a Rails developer's advice.

  • djingis1 (unregistered) in reply to quackers

    Indeed. Obviously, a Rails developer's advice must be discarded purely on the premise that they are a Rails developer. Whether or not they actually have a point, is irrelevant.

  • Sarcasto (unregistered)
    Comment held for moderation.
  • Ron Fox (google) in reply to djingis1

    ...though in this case I think what they have is an excuse to be undisciplined rather than a point. Here I am in the editor and now I have to roll through the commit history to understand the motivation for the code I'm looking at? Not if I can help it.

  • DocMonster (unregistered)

    I've been at quite a few places that were in the mindset of "self-documenting code", i.e. you don't need comments because it should be clear what your code does. While I agree to a point, I feel comments are useful when they outline an algorithm or a section of code that might not be apparent what is going on, or to add clarification to why something is done the way it is.

  • Cheater (nodebb)

    "I ended up examining some board games with Richard Stallman"

    Any recommendations Remy?

  • Nick (unregistered)

    same way it needs tests: it should exist, but we don’t want to have to create it.

    Maybe it was having a mentor at my first job who was 110% in love with unit tests in python, or the near complete absence of automated testing at my current job, but I love writing tests. It makes things right with the universe and makes fixing bugs 80% easier.

  • TheCPUWizard (unregistered)

    Big fan of having a hierarchy of information.

    1. Code that is clear enough to understand how it works.
    2. [User Stories / PBI] to explain why the effort is being expended.
    3. Tasks to explain the steps needed to achieve the above
    4. Commits with enough detail to describe how they fit into accomplishing the task - what is new, what is changed, what is removed
    5. Tests for each level of code
    6. Current and Historical defects associated at any of the above levels.

    With good tooling all of these are integrated [right into the IDE] for the code.

  • djingis1 (unregistered) in reply to Ron Fox

    It's not that black and white.

    His point is that a commit message and the code that was committed are linked to the same point in time. And that has its advantages. It's a good point.

    Your tooling apparently doesn't work nicely with that workflow, so for you, that doesn't work. Surely yours is not the only tooling that doesn't work nicely with this workflow, so it may not be the correct workflow for many people. That's a good point, too.

    Vim in combination with some awesome plugins by Tim Pope can make it trivial to grab the commit message that accompanies a certain line of code. Similarly, newer editions of Visual Studio make it trivial to get the commit(s) that changed a method or class. So with this tooling, the workflow might work just fine. I wouldn't know, I haven't tried.

    Again, it's not that black and white. There's no silver bullet.

  • djingis1 (unregistered) in reply to djingis1

    Addendum:

    And MY point was that it's a bad idea to dismiss an idea simply because it's coming from a Rails developer. I don't care if the guy actually has a point or not.

  • Bananafish (nodebb)

    Remy says:

    Comments are rough. I always take the stance that code should always be clear enough to explain what it does, but you’ll may need a comment to explain why it does that.

    I'll may need to think on this for awhile....

  • Remy Porter (google) in reply to Cheater

    Well, the game we were puzzling over was Bambolo, which is what happens when Germans reinvent Jenga. It's interesting, but I'm not huge on dexterity games. Also, it makes a huge mess.

    I am a fan of social games, so I enjoyed playing a few rounds of Spyfall. I'm also big on co-op, so if you're looking for a more general game recommendation, I'm big into Arkham Horror.

  • isthisunique (unregistered)

    The rails developer does have a point within reason. Cluttering code with comments is really annoying.

    Actually the point really does go beyond the specific programming language and into the position of the language experts. Knuth was around more at a time where fluency and literacy in programming was uncommon.

    Put it this way, lets say I can read German natively. Then a line of English for each line of German is going to be redundant and actually very annoying. The solution to this these days tends to be self documenting code but even then there are things that you really want to explain such as deeper overall meanings. Self documenting code is actually code that is simply organised sufficiently with goot meaningful words or phrases used for identifiers giving the best of both worlds. Such code needs less explanation, is quicker to read as it leverages both fluent English and code reading skill, etc. This means things like avoiding mnenomics.

    Comments in modern programming where rosetta comments more often than not get in the way tend to be functional. For example, a warning that a line of code might have side effects or problems in certain cases. Comments can also be used to extend the language in various ways. Where comments do explain things, it might be pitfalls or things that are not obvious up front.

    Because comments get in the way of the actual code people are trying to read and work on, you have to be careful not to be too gratuitous. Commit messages are a location where you can get away with being more gratuitous.

    The point is that over time, things have changed and in terms of how we look at a language directly, Knuths approaches are less generally applicable and now more restricted to certain scopes such as academia or where you are transcribing expert knowledge, need expert verification of an algorithm, very complicated algorithms, etc.

  • jkshapiro (nodebb)
    Comment held for moderation.
  • Steve_The_Cynic (nodebb)

    The point about "why" versus "what" or "how" is best shown by a line of code and some potential comments:

    i++;

    A comment that says "add one to i" doesn't add to the information provided by the code itself, especially when it is left alone and the code is changed to --j; (I'd argue that this part is specious; see below)

    A comment that says "advance to the next element" tells us why we are adding one to i (something the code itself doesn't do), and might remain true when the code is changed as above. (That "might" is why the part above is specious. If it doesn't remain true, the comment is just as wrong as the one above becomes...)

    A comment that says "fix bug 5427" is of no use at all.

    Putting "why" information in the commit log isn't right either, because it isn't there when I look at the code. I must look for it elsewhere, and even if the IDE (etc.) makes that easy, it's an extra step, and the commit log doesn't explain why that line is like that in a 30-line insertion.

  • Herby (unregistered)

    Comments. Comments! We all write comments. The problem is that they need to be useful. I take the stance that you need to write comments to yourself, because the "you" six months from now will likely NOT understand all that you did when you wrote the code.

    So, write comments to explain the code to the 6 months in the future you, because you will hardly recognize the code then, and if it is any longer, the magic is gone, and your brilliance will have faded away, long long ago.

  • Discouraged (unregistered)

    If you can't write useful comments, you should not be coding. At least, you should not be coding anything which someone else might need to work on.

    If you can't write a sensible test suite, how the hell did you debug the code? Oh, you ran it once and it didn't crash? Good - don't let the door hit you on the way out.

    The only code that should reach integration is clearly written, documented, and tested code.

    Amateurs and hackers not welcome.

  • Ex-lurker (unregistered) in reply to isthisunique

    <quote>Put it this way, lets say I can read German natively. Then a line of English for each line of German is going to be redundant and actually very annoying. </quote>

    Let's run that analogy a little further. Suppose every english line is displayed in a different, soft color. Your eyes now can tune them out and ignore them completely, until you get to the actual part where you're having trouble reading german, which is when you'll want the extra information that you can get in that english line.

    Congratulations! Your point was just unmade by the ONE feature that is guaranteed to be present in even the crappiest IDEs for the crappiest languages. (Except Whitespace)

    PS: I hope this forum's current software allows for us to insert our own tags.

  • Ulysses (unregistered)

    Pervasive comments are guaranteed to drift from reality like a drug addict. So non-doxygen comments need to be sparse at most, and should speak from a higher level. Particularly interesting or tricky bits deserve comments. Very little code should be of such ilk though. If a significant amount is, it most surely sucks. It needs to be broken up a bit better, or it suffers from an architectural WTF altogether.

    There's an unspoken notion that if one writes hand-holder comments about every line or change, another can then work on/with it, and skip the part where he actually reads and grasps the content before he gets any bright ideas.

    It's nothing but a cop-out. Competent devs don't need or want it. The only ones who have ever complained about my lack of logorrhea have been dumb scriptkids. The last lamer is overly verbose in both speech and text. It's no surprise, as she needs everything spelled out for her, and still efficiently deflects most information.

    This example is a WTF mini-article in itself: she stepped through some code, not mine: Enqueue(...); Wait(...); She actually concluded out loud that Wait() does the actual work. When she stepped through it again, the action occurred between the two calls. She almost jumped out of her chair as she looked at us all befuddled.

    Easy Reader Version: Heavy comments are for crappy code and crappy coders. Lose both.

  • Lawgiver (unregistered)

    Not from me, but: Programming is the art of telling another programmer what you want the computer to do.

  • Norman Diamond (unregistered)

    The reason for this comment is to explain to the future me, after 6 months, what the reason for this comment was.

  • isthisunique (unregistered) in reply to Ex-lurker

    Ex-lurker

    Sure, highlighting, code folding, extra provide an assist but that's all they do. They do not eliminate the problem entirely. Your eyes still have to move more, it may be harder to register but your visual system still has to process and filter out the noise even if it is assisted, there is still more noise, if you do certain things like hotkey duplicate a line and move it up then it must be moved up more and may bring about havok if you have folder comments in the path, search or find in file is going to pick things up in the comments, you need to also maintain the comments when you maintain the code, etc. By just colouring them out even if your visual system can filter them out you've just lost half your foveal field of vision. I don't think that human vision will be able to fully filter it out all the time. The only way to do that is pretty crazy, requires perfect striping and would need the eyes to be slightly out of vertical alignment. It's just silly. Even at a glance without comments in the way there's a benefit to seeing the structure of code uninterrupted.

    The point is it's just YAGNI or bloat and if you find yourself having to write rosetta code then that might raise a few questions. Perhaps your standards for your target audience are too low for example. I often deal with a lot of thick sophisticated code even after a heavy dose of DRY and if I also had to maintain a swamp of comments as well as good code it would ruin my life. As with most things, code, comments, etc usually too little is better than too much. If you do too much it will almost never show directly. If you do too little, it will eventually announce itself. This is just a fundemental rule. For comments your minimum standard tends to be doc comments although if your codebase is not well designed and subject to a lot of alteration this can be a problem as it will introduce massive drag. To be honest, a huge number of codebases do not even bother with doc comments which can be a bit of a shame.

    The number one rule is don't do something unless it is needed or really adds value. The shame of it is people tend to interpret this as not having to bother to name variables properly, indent properly, escape properly, handle errors properly, handle unexpected cases properly, etc. There is another golden rule that becomes apparent and it is a bit of an unfortunate one. In terms of maintainability, time spent on code tends to be far more valuable than comments. It's only occasionally that comments are valuable enough to put in. So unless you have lots and lots of resources to dedicate on a codebase to get every aspect perfect and close to correct the first time then you're not going to want to indulge too heavily on comments.

    I'm not against comments but I am against comments for the sake of comments and every detail matters. You can't say it doesn't matter because it's a bit less obvious, because it is shaded out. It's still there, it still has an impact. I do have it a bit easy because I've worked on a lot of other codebases, opensource, inherited, my own after years and so on so I am fairly confident about exactly how far I need to go with comments to uphold a good level of maintainability. It's quite often when working on my own codebases that when I find a bug and finally trace it to the line there will be a comment there giving warning about an uncertainty or an unhandled case. There are cases where you have to work out intention but that becomes easy after a while especially after failing all else you can establish your own intentions which are usually about as good or lead you down the right path.

    You haven't unmade my point but rather you've raised a few points about yourself. Sure, assists are helpful sometimes and relevant to this discussion. What isn't is your attempt to push comments as a zero cost artifact and your over confidence. You seem to be pushing for comments for the sake of comments if your trying to push a zero cost agenda and that simply isn't viable. It's an extreme position to take. I don't know if you're trolling or what because on the face of it it's just silly pseudo expert stuff. It's almost comedic. Are you being sarcastic and trying to immitate a type of person with mockery? Because if you're just going to have your IDE dull them like that so you can filter them out so you can ignore them you might as well then delete them because it seems they must be pretty useless if you don't need to see them. In fact the example I gave specifically was that they were useless so you're saying it's fine to have useless stuff because you can lowdark it.

    The thing is though, I would like something like effectively zero cost comments at least from my perspective and in relation to my coding styles. For me the best thing in that vain is external documentation but the problem is with that is that it drifts just as the rails guy alludes to in a way. Commits are a good start, the only thing is that it's just a single string and you would have to manually point out lines in code, files, etc. I use something for code review that allows comments per line and so on. It might be nice to see something like that integrated into a VCS per commit (and to have a commit that purely adds comments like this). This can also drift over time but as the rails guy points out, initially it maps to a point in time so you can trace its ancestry basically in the same way you might do blame, etc. I say zero cost but nothing is literally zero cost. It would still allow me and others to be far more gratuitous with comments though with less of a concern about cluttering code and without such an obligation to maintain comments added to the same degree.

    If shading them gets them out of the way for you in your circumstances then that is absolutely fine. That doesn't entitle you to dismiss the notion that other people might want superfluous comments completely out of the way of their code.

  • isthisunique (unregistered) in reply to isthisunique

    I forgot to add a bit. If you reach a point where you struggle with the German, 99% of the case that's a matter of RTFM. Your German sucks and the solution to that is to not embedded the English-German dictionary throughout the document but to brush up on your German. If it's the 1% case then perhaps add a comment, it may be needed in that case. For a fluent developer things are switches, 99% is a case that needs a comment, 1% is a case that language comprehension fails. However, such developers often only have a problem understanding the code once per thousand or more lines of it unless someone has written code in a way that is somehow obfuscated like using only expletives for variable names.

  • But I am a robot (unregistered)

    Comments: Brief, entertaining, useful If its not 2 of those 3 then don't bother

  • dkf (nodebb) in reply to Steve_The_Cynic

    A comment that says "fix bug 5427" is of no use at all.

    Not necessarily. I like to keep my tickets in the repository so that I don't lose track of them, so the ID (the only useful bit) remains useful. Yes, a blame log might help, but it doesn't really help very much when you're dealing with code that's a few decades old; some things live for a long time, in some cases out-surviving their original authors entirely.

  • Zemm (nodebb) in reply to Lawgiver

    Do you have the reference to that? That's a great "Thought of the day" for our board.

    Addendum 2016-08-25 10:05:

    Programming is the art of telling another programmer what you want the computer to do.

  • Zemm (nodebb) in reply to dkf

    A comment that says "fix bug 5427" is of no use at all.

    Not necessarily. I like to keep my tickets in the repository so that I don't lose track of them, so the ID (the only useful bit) remains useful.

    I'm on the fence when it comes to this. It does explain the "why" the code is like this (look in the bug ticket, minimal typing by the developer: all the information is in the bug-tracking system). When I think a bit of code needs the extra clarification, I do often add the ticket number and try and add a short comment so that at least I can show more reasons behind this strange logic methods.

    But there is always the risk of losing that information when moving between bug-tracking systems. Even on our project we've changed JIRA prefixes four times in three years. You know the age of the bug fix/feature request by the prefix left in the code. Luckily though that searching for the old prefix automatically redirects to the current ticket.

    I even came across some code today that was marked with an ancient ZenDesk ticket number (in use before JIRA) which shed some light on WTF this thing is. The git commit message was basically the svn revision number with the message something like "Thursday" along with 200 other unrelated files in the one commit (svn history was imported into git).

  • Bananafish (nodebb) in reply to Zemm

    The comment should be:

    // Fix for bug DW-05427: Inventory miscount if box quantity > 24

    THIS comment makes sense with reference to logged bugs. It is of no use to know the bug number within the code if I have to look it up. We don't need to read the entire bug report to know what the fix was for. It is also helpful to see this in the actual code where the fix occurs:

    // DW-05427: 08/25/2016 // Enumerate box quantities from Inventory instead of coded list ... code ... // DW-05427: 08/26/2016 // Inventory item 01-554-A special case ... code to handle this special case ...

    And here, it is obvious the code was changed so instead of a hard-coded list this information is gathered from the numbers on the actual product records from inventory so that the possible box quantities are displayed in real time. It is not necessary to comment every line in the code ("create a new integer for use as a counter in the array", "cycle through the array", "return the value of the array index", "add one to i"). There isn't reason to put other comments in there unless you have a need to accommodate special cases or if the code may be seen as WTFery because it's not so obvious how the code does its job. Maybe there's 24 in a box but this particular item is sold in 12-box pallets, so the actual quantity is 288? Maybe you need to do voodoo or majick to get the database to spit up information because of the way the data is arranged? I dunno... just making that part up. And, absolutely under no circumstances is there any reason to comment out the old code that was changed so it's still visible. I have seen code where small revisions over the years have resulted in 10 lines of the same variable assigned different values, with 9 of them commented out AND each containing a comment as to the reason for the change (and change back when that didn't work).

    Yep, tags might be a problem if you change systems and/or prefixes. Makes no sense to import and renumber all your bugs and refactor all your code to contain the new numbers on the new system, and it may or may not be possible to save all the information from the old system for a variety of reasons. But if you have short meaningful comments like this in the code along with full descriptions in bug reports and a happy medium in the commit log you will make a lot of people happy when they need to review your code.

  • Ex-lurker (unregistered) in reply to isthisunique

    "highlighting, code folding, extra provide an assist but that's all they do. They do not eliminate the problem entirely." Making a problem disappear isn't the only way to deal with a problem. Making it very easy to deal with to the point it becomes trivial is most of the time the most cost-effective solution. Following your reasoning you shouldn't have a car because you still have to walk a little after you get out of it, thus "they do not eliminate the problem entirely".

    I "push for comments for comments' sake" just as much as you push for a "absolutely no comments allowed" stance, i.e. I don't. You really streched my comment wide with a lot of suppositions and guesswork. Next you might say I think like that due to a rough childhood or an abusive teacher or some other BS. You seem to be under the impression that I love littering my code with "//adds 1 to i" for every i++ I write. That's an erroneous assumption and it's entirely on you. I like having a small comment above a line that is more complex than the average. At this point I usually have two choices, either a slightly above average complexity single line which I clarify with a one-line comment that will later confirm what I suspect that code does or I can unroll that code line unto a 20 lines block of code to do the same thing with lesser complexity, thus not needing any comments. Per your previous post you appear to like the codeblock approach more (as it is self-commenting). But then wouldn't that block require more of the screen estate? Wouldn't your eyes need to move more? (By the way, your argument could easily be used to defend a removal of blank lines. I don't think you really agree with that)

    "Because if you're just going to have your IDE dull them like that so you can filter them out so you can ignore them you might as well then delete them because it seems they must be pretty useless if you don't need to see them. In fact the example I gave specifically was that they were useless so you're saying it's fine to have useless stuff because you can lowdark it." Most of the time my brain is in high gear and I don't need that one-line comment to immediately get what the line it references does. But I'm human (maybe you're not?) thus sometimes my brain is in a slow gear or in need for a coffe and that comment line helps me get what the code is supposed to do. And when I'm on a high gear it will still be alright that it's there because I'll just tune it out.

    Once again, let me remind you: I'm not advocating being swamped in comments. That would drown the code in noise, as you said. But if you have let's say 6 comment lines spread over a screen displaying 40 lines of code I find that extremely easy to deal with.

    As in all things in life, there's a call for moderation. Too much of a thing is bad, too little is bad, I defended having a bit more than you think is adequate and you responded as if I was advocating for a sea of comments in which a solitary line of code floats.

  • Bananafish (nodebb) in reply to Ex-lurker
    As in all things in life, there's a call for moderation. Too much of a thing is bad, too little is bad, I defended having a bit more than you think is adequate and you responded as if I was advocating for a sea of comments in which a solitary line of code floats.

    I would have to agree with you. Having "a bit more" is better than having too few or none.

  • isthisunique (unregistered) in reply to Ex-lurker
    Comment held for moderation.
  • cây nhân sâm tươi (unregistered)

    Những người bán nhân sâm Hàn Quốc cho biết, nhân sâm được trồng và nhân giống tại nhiều nơi. Tùy vào đặc điểm nguồn nước, thổ nhưỡng và khí hậu mà hoạt tính cũng như giá trị nhân sâm khác nhau. Do chỉ bảo quản tối đa được trong vòng 7 ngày nên nhân sâm tươi Hàn Quốc đưa về Việt Nam phải được bảo quản ở nhiệt độ thấp. Khách hàng có nhu cầu mua nhân sâm Hàn Quốc ở đâu tại Việt Nam cũng phải đặt hàng trước khoảng 2-3 ngày, đặc biệt là khi mua loại nhân sâm Hàn Quốc 6 năm tuổi.

    Nhân sâm là sản phẩm chăm sóc sức khỏe cao cấp của Hàn Quốc. Nhân sâm Hàn Quốc được đánh giá là một trong những sản phẩm ưu việt qua quá trình chế biến thì hàm lượng ginsenosides được tăng lên rất nhiều, nhân sâm lại mang tính ôn nên phù hợp với nhiều đối tượng và đặc biệt là rất tiện dụng cho cuộc sống hiện đại.

Leave a comment on “Accuracy in Comments”

Log In or post as a guest

Replying to comment #:

« Return to Article