News for hackers. Stuff that matters.
Re:Golden rules for becoming a better programmer by dozzie on Tuesday January 26, 2016 @07:06PM (#10977260)
Oh yes you do need. Plenty of time you need to explain why the code does what it does. You rarely need to explain only how it works.
Re:Golden rules for becoming a better programmer by joshka on Tuesday January 26, 2016 @07:44PM (#10977437)
I've seen lots of people make this assertion, most of the code I've seen doesn't need more than the how. Can you give some examples of well written code where there's significant amounts of comments that explain the why?
Re:Golden rules for becoming a better programmer by kazinator on Tuesday January 26, 2016 @08:23PM (#10977572)
In certain types of code, the purpose of some logic is not clear by itself.

A comment can be very valuable to answer the question "why the heck is this being done here?"

It's valuable because it represents hard-earned knowledge.

That thing that is being done there wasn't being done there before, and it took weeks to figure out that it had to be done there, for the sake of such and such a race condition that can occur, when the interrupt goes off just when we are doing such and such elsewhere in the driver. It was hard to reproduce the ensuing problem and trace it to this.

The comment explains how the system will fall down if not for those lines of code.

Systems that have a lot of (or not even a lot of) concurrency going on can be very hard to understand from the static view. Our aim is to produce the dynamic view: to bring to life the collaboration or sequence diagram that we had on the whiteboard. But it's not obvious how (or whether) the code actually does that (and only that, ruling out unwanted scenarios).

"Why" comments can also make the code more navigable, because they mention other identifiers elsewhere in the code which are related to this code here in ways which are not obvious. The text editor can jump from these mentions to their definitions, which is a big time saver for someone trying to understand that situation.

Re:Golden rules for becoming a better programmer by enraged_camel on Tuesday January 26, 2016 @09:55PM (#10977899)
Sometimes you have to work with a third-party system or interface that is sending your application dirty data, and you need to account for it in your code in creative ways that may not be obvious to someone who is just reading it.

For example in our current project w'ere working on a front-end piece that connects to a CRM application where no rules or constraints have been set up or enforced for a long time. We're talking stuff like zip code fields having values like "I don't know" or "XXXXX". So for every function that receives such values from a lookup, we have to clearly document those edge-cases in the comments and explain how the function deals with them.

Re:Golden rules for becoming a better programmer by joshka on Wednesday January 27, 2016 @12:47AM (#10978465)

  ZipCode GetZipCode()
  {
     var result = _crm.GetZip();
     return isValidZip(result) ? new ValidZip(result) : new InvalidZip(result);
  }

  class ValidZipCode : ZipCode { ... }
  class InvalidZipCode : ZipCode { ... }
No edge cases, perfectly 'documented'.
Re:Golden rules for becoming a better programmer by codingdave on Wednesday January 27, 2016 @09:54AM (#10980261)
How do you consider that to be documented?

Why do you return a different class for invalid zips? Is it OK to use invalid zips in all cases? If not, why not throw an error? If so, what benefit does the separate class give you?

Because that code doesn't handle bad data - something in the objects or some other function must handle it, and this code doesn't really tell us what is going to happen with a bad zip. It just tells us that the code noticed it.

This is exactly why comments can help.

Re:Golden rules for becoming a better programmer by joshka on Wednesday January 27, 2016 @01:04PM (#10981681)
See the null object pattern. Encapsulate all such behavior you've mentioned with appropriate OO patterns, and stop writing procedural code spread all over the place that has to rely on comments to inform you about the right way to handle the bad data. Handle the bad data cases simply and specifically.

Feel free to add some code that explains your use case and where you think such comments are required...

Re:Golden rules for becoming a better programmer by codingdave on Tuesday January 26, 2016 @10:52PM (#10978087)
Yes, all over the place, explaining the business reasons behind the algorithms, or why some code was put in place to resolve a specific browser oddity (usually with dates and versions so we also know when it can be removed in the future). We also use comments to indicate when code is written to follow a specific decision from the CEO, and was not just an arbitrary design choice by us coders.

In short, we make sure that a coder can read the code and understand not just the code, but how it fits into the larger business.

Re:Golden rules for becoming a better programmer by joshka on Wednesday January 27, 2016 @12:55AM (#10978490)

  var browserOddityHandlers = [
    { browser: "IE", date: "2001-08-27", version: 6, odditiesHandlers: [ ... ] },
    ... ];
Code is rarely an arbitrary design choice. Such design choice decisions as you mentioned belong in your source repository message IMO, rarely in the code.
Re:Golden rules for becoming a better programmer by codingdave on Wednesday January 27, 2016 @09:45AM (#10980208)
So when you are coding, and start looking at an existing function, you are telling me that you go back to your repository and read through the entire commit history for that function?
Re:Golden rules for becoming a better programmer by joshka on Wednesday January 27, 2016 @03:54PM (#10983227)
If any function has such a significant commit history that this is a problem in your code, there's probably a violation of the SRP right in front of you. Stop modifying it. Write modules that are small enough that their usage is obvious and you'll find it less likely that you're changing code so often that commit history on a function matters.

In the case of the CEO mandated approach, write a test that explains it. Why comment something that can be tested.

  [Fact]
  void FooReturnsBazBecauseJoeMadeUsDoThisInsteadOfBar()
  {
    var actual = _someObject.Foo();
    Assert("baz", actual);
  }
This way, if that code ever is changed, the comments and the code don't get out of whack with each other. Instead, you'll have a broken test. At that point it becomes obvious to reach for understanding as to why that test is there. The first step is read the commit history. If your commit history is useless, you talk to the dev that implemented it, or go back to the spec that drove it. These solutions are still 100x more useful than a comment.
Re:Golden rules for becoming a better programmer by st3v3r on Tuesday January 26, 2016 @08:13PM (#10977548)
Where the code itself looks like it's written crappily, but cannot be implemented in a clean way, due to the API used or performance or other issue.
Re:Golden rules for becoming a better programmer by joshka on Wednesday January 27, 2016 @12:40AM (#10978446)

  class CrappyApiWrapper
  {
    CrappyApi _crappyApi;
  
    void DoSomethingNice() {
      crappyApi.DoSomethingCrap();
    }
  }
Re:Golden rules for becoming a better programmer by falcolas on Tuesday January 26, 2016 @11:28PM (#10978207)
Here's the easiest example I can come up with:

    // Optimized this code as it's a hotspot. Does <x> but quickly.
Re:Golden rules for becoming a better programmer by joshka on Tuesday January 26, 2016 @11:50PM (#10978289)
how is this better than:

  void DoActionOptimized() {
  ...
  }
Re:Golden rules for becoming a better programmer by codingdave on Wednesday January 27, 2016 @09:56AM (#10980268)
Because at one point, the code was not optimized, so it already had a function name. Are you really going to rename all instances where that function is called so it is named based on a single commit, instead of its actual purpose?
Re:Golden rules for becoming a better programmer by joshka on Wednesday January 27, 2016 @01:18PM (#10981787)
There are many ways that are non breaking to implement this. I chose a particular one for example's sake. In reality, extracting an interface is a more valuable refactoring, and a likely valid one given that the optimization tradeoff is happening. So MemoryOptimizedFoo : IFoo, SpeedOptimizedFoo : IFoo...
Re:Golden rules for becoming a better programmer by lomnakkus on Wednesday January 27, 2016 @05:41AM (#10979350)
In fact you might also want the un-optimized code around and run the optimized version "against" the un-optimized version (in tests) to see if they actually do the same thing.
Re:Golden rules for becoming a better programmer by joshka on Wednesday January 27, 2016 @01:10PM (#10981722)
Extract an interface (IFoo). Implement Foo : IFoo and FasterFoo : IFoo. Write tests to confirm all implementations of IFoo act equivalently. Write performance characteristic tests around FasterFoo.
Re:Golden rules for becoming a better programmer by lomnakkus on Friday January 29, 2016 @01:48PM (#10997465)
Exactly.
Re:Golden rules for becoming a better programmer by zachsnow on Wednesday January 27, 2016 @01:14AM (#10978547)
Optimized how? Faster? Less memory? Something more subtle?
Re:Golden rules for becoming a better programmer by joshka on Wednesday January 27, 2016 @01:12PM (#10981737)
That's what naming is for. MemoryOptimizedFoo, FastFoo, ...
Re:Golden rules for becoming a better programmer by joshka on Tuesday January 26, 2016 @11:53PM (#10978296)
I'm going to pull the "shutup and show me the code" plug on replies to this. If you're still writing prose in response to my question, you're in the exact same bucket at those I mentioned making the assertion.
Re:Golden rules for becoming a better programmer by piess on Tuesday January 26, 2016 @07:19PM (#10977322)
You can put this in the summary
Re:Golden rules for becoming a better programmer by dozzie on Tuesday January 26, 2016 @07:26PM (#10977360)
You can't more often than not. Often the "why" is an implementation detail regarding a single statement, and those shouldn't make their way to a function summary.
Re:Golden rules for becoming a better programmer by joshka on Wednesday January 27, 2016 @12:58AM (#10978499)
If there's hidden meaning in an implementation detail regarding a single statement extract that value to one of the following: a) a variable b) a method c) a class All of these provide a mechanism for documenting the code without comments. Show me where you think this doesn't apply.