Comments by "Mikko Rantalainen" (@MikkoRantalainen) on "The Beauty Of Doom 3 Source Code" video.

  1. We have a rule for our team that you have to document all public methods for a class. You don't need to write title line if the function name is descriptive enough but you have to document non-trivial arguments and you have to define the return value accurately. If you don't like writing documentation, try to mark methods as private as much as possible. The idea of documenting the public interface is similar to design-by-contract in Eiffel language. Without documenting the expected behavior in human readable form, you cannot know how the method should be fixed in the future when you hit some case it cannot handle correctly. Nobody expects you to comment individual lines unless those are a workaround for some external component. In that case, you should document why the workaround exists and why it works because that behavior depends on external component and if the external component ever changes, you need those comments to understand the change in behavior. And if you write any kind of workarounds, try to do feature detection instead of checking for version numbers to decide if the workaround should be applied or not.
    1