• David.Poole - Friday, June 8, 2018 1:21 AM

    I've just finished reading "Clean Code" by Robert C Martin.  It takes a dim view of commenting code preferring instead to refactor the code to the point where all functions and methods are simple and have meaningful names.  The view is that if the name of your function cannot express what the function does then the function is probably too complex and needs refactoring.

    It also emphasises the order in which the properties, methods and functions appear in a program.  Reading from top to bottom the main method should read like a summary of what your app does.  Below that comes the functions that it calls as the details of the summary.

    Personally I like having JavaDoc type comments and the tool to assemble them into a publishable format.  But then I enjoy documenting things and the disciplines that are required to keep this up-to-date.
    The problem is that the comments are not intrinsically connected to the code so nothing verifies that the comments match the code.  Perhaps the better approach would be to use BDD as the documentation or to focus on commenting the tests rather than the app code?

    When committing something to source control the text for the commit comment is "When applied this..." followed by whatever the commit is actually trying to achieve.  This encourages small commits of workable code.

    In terms of commenting databases using the MS_DESCRIPTION extended property for DB objects allows Red-Gate SQLDoc to pick up the descriptions.  Other databases seem to have standardised on using the COMMENT ON object IS 'suitable description'; syntax.
    If you don't attach useful business descriptions to your database objects then you will reap the wind.

    I do kind of agree with that in general. What can be useful is WHY code is doing a particular thing - I find this prevents someone coming after going on a journey trying to work out why an obscure thing is being done, thinking it's useless and deleting or circumventing the code, only to find out the reason through breakage. Comments for intent only is my general rule of thumb - unless it is to explain some really obscure operation.