in reply to An Introduction to Literate Programming with perlWEB

The sort of documentation provided in the example seems like it would be useful in a CS101 course.
However as others have mentioned, completely impractical in any realistic situation

With that level of documentation, almost anybody could understand what the code is trying to do. However the documentation is pandering to people who do not have the capability of writing code at the expense of those who do.

Documentation is a tricky thing; you must explain for those who may not be familiar with the specific thing you are doing. But you must also not hinder those who do know what they are doing. People who do not know what a main function or variable declaration is are not part of the target demographic at all.

Both cases are equally hard to understand; in one, you must puzzle out the code yourself. In the other, it is faster to puzzle out the code yourself.
However once you've figured out the code, things change...in that first case, updates are easy. In the second case, updates require writing another essay.


If I must choose one or the other, sign me up for the office that enforces no commenting! :D

  • Comment on Re: An Introduction to Literate Programming with perlWEB

Replies are listed 'Best First'.
Re^2: An Introduction to Literate Programming with perlWEB
by Anonymous Monk on Jan 15, 2009 at 18:37 UTC
    With that level of documentation, almost anybody could understand what the code is trying to do.

    I think that is the OP's point and have no idea why anyone would want to argue that the goal of very easily understood code is a bad thing?


    However the documentation is pandering to people who do not have the capability of writing code at the expense of those who do.

    Dude, at any company, school, or hobby group there are going to be programmers of varying skill. You may argue for or against Literate Programming but I am inferring your argument here is that you want to jealously guard your code and not let those people be able to figure it out. People that code less well than me may well deserve explanations and mentoring and not rude dismissal, got it?

[reply]
      All that documentation does not actually make for easily understood code per se. It does make a longwinded story that explains your code in horrifying detail, so your code should eventually be understandable even if the code is pretty bad.

      The problem here is that your documentation is geared to people who don't code at all. Illiterate programming, if you will. Such people will not be looking at your code anyways!
      Your target audience knows what a main function is. They know what a variable is and how to declare it. They know about loops and return. They are literate enough to read your function name and your variable names, and they have basic logical reasoning skills. (if they don't, then HR needs to be replaced)

      Much like the proverbial instructions on how to remove sand, written on the bottom of a boot, I see
      "Here we define the main program."
      as a subtle insult to everybody capable of opening the source code to read that.


      When I say I'd prefer to work at a company that bans even comments over the "literate programming" scheme (as presented here), I mean it in terms of maintaining other people's code.
      People are not going to be committing Obfus to the repository, obviously. And since they're not allowed to add comments, they'll have to write cleaner code for their own protection.
      • Naming functions accurately and specifically.
      • Using explicitly named variables
      • Arranging algorithms to be clear and straightforward
      Say I open up a file, and start reading through the code... it is all nice until I come across: @polarCoordDrillSites = map { ... } @drillSites;
      Embarrassingly I don't know about map. But the code doesn't need a comment explaining the obvious. It doesn't even need the guts of the code to explain the line! It CERTAINLY doesn't need a paragraph of english prose throwing chaff into the file.
      If there is a problem with the code and I need to fix it, I will visit http://perldoc.perl.org/functions/map.html and look up the details of how map works, make sure it is working the way I think using test.pl, and presto.

      On a totally unrelated note, map seems to be a lot less complicated than I had imagined all this time.
[reply]
[d/l]

In Section Meditations