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