News for hackers. Stuff that matters.
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.