1. 4
  1.  

  2. 2

    I’m not so sure about this. Some people also seem to think that documentation will always make things easier if something is a bit difficult to understand. In a lot of cases I don’t think this is true; for example a codebase just takes some time to really understand, no matter how much documentation you write. More documentation doesn’t always make stuff better; sometimes it’ll just service to convolute things.

    I am a big fan of inline documentation. This can be tooltip on a web UI, a helpful line of text in the -h output of a commandline application, or a well-written function comment. Writing external documentation (wiki pages, SOPs, totorials, KBs, etc.) are not just difficult, but will also tend to go out of date quickly, and are cumbersome to use.

    Not saying that all external documentation is bad; some is good. But you need to think carefully about what and how much. And in general, the best documentation is not having to look at documentation.


    Oh, and the author’s plug for his book seems rather … dubious:

    Blog for your Life: How to Make Money, Build a Career, and Create a Lifestyle through Blogging

    DO YOU WANT TO MAKE MONEY? BUILD A CAREER? BLOG AND LIVE A GREAT LIFESTYLE? If so, then this is the book for you.

    Learn the SECRETS to growing YOUR blog from someone who has actually DONE it.

    Previous article is even worse.

    I’m not so sure about the alleged success of this weblog, either. Most of the articles are very superficial; it’s been around for only about 18 months, and it has all of 27 Twitter followers.

    1. 1

      I took issue with his N-queens example. If I had a line of code like that, my feedback would not be to add a comment that explains what it does. My feedback would be to refactor the code, add functions, add detailed variable names, and do whatever else is necessary to make it so that the comment isn’t needed in the first place.

      Adding a comment to the n-queens solution does allow me to see what the code is, but it doesn’t allow me to see how the code finds the solution. It doesn’t allow me to verify that the solution is correct. It definitely does not allow me to modify the solution (maybe I want to run n-queens on a 3-d chessboard).

      1. 2

        Exactly! It’s very annoying to fight against co-worker that tries to code golf some functions… Chaining map and filters with one letter lambdas all around saying « yea, but it’s very idiomatic »…