1. 6

  2. 2

    commentanental drift™

    1. 2

      I’ve heard one of the best ways to handle comment drift is instead of letting people look up code first => docs second, make sure that all your tools do docs first, code second.

      What ends up happening is people code against the documentation, then check implementation if they’re worried. This makes the documentation the contract of behavior instead of the code your contract of behavior.

      Negative? Outside of very large firms, it’s difficult to spend time getting tools to do this automatically for your coworkers.

      1. 2

        That example of a good comment would serve better as a commit message imo. Maybe a portion of it is ok in the file.