Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery
 
PerlMonks  

Re: Programming *is* much more than "just writing code".

by graff (Chancellor)
on May 09, 2007 at 02:59 UTC ( #614287=note: print w/replies, xml ) Need Help??


in reply to Programming *is* much more than "just writing code".

Comments serve a different purpose to documentation. And documentation does not belong in source code files.

Are you talking about Perl here? Are you saying that using POD in perl code is wrong in some way? I cannot agree with that. (And just where should the documentation be?)

Okay, programming is hard, and writing proper documentation is at least as hard -- often harder: striking the right balance of natural language coherence and logical/procedural accuracy is really another form of the common tasks in programming: problem-solving, puzzle-wrestling, optimizing, getting things into the right operational sequence, working out the best way to refer to things, and so on.

(Let's face it, every higher-level programming language is really a sort of subset or reduced adaptation of a human language, designed to make control of computers possible for a wider range of humans, and easier for the ones who really understand the machines. Comparing this to mathematics, chemistry, etc, is disingenuous -- people in those fields need text books, in a human language that they know, in order to learn the symbols and the syntax for combining them. And that's a lot of work!)

So doing both the code and the documentation -- and maintaining both of them to keep them in sync -- is really hard. But that's a lousy reason for not doing it, and based on experience, I tend to believe that the code is easier to write (and to get right more quickly) when the documentation has been written first, and is as clear and unambiguous as the code needs to be. What I mean is: the coding is less work when the documentation is done first.

An added nice feature about that, when you're able to do it, is that you can show the docs to people who don't know how to program (e.g. a customer or sponsor), and assuming you are dealing with people who know how to use the same human language that you are using, they can understand it, react to it, make suggestions for improvements, and so on. Even though the population proficient in any given human language is "limited", it's a lot bigger than the population proficient in a given programming language -- English, French, etc are good for somehting, even to programmers.

And a nice thing about doing it as POD in your Perl script is that it's always right there for you, the programmer, and it's also really easy to present to others, the non-programmers, in a clear, human-readable form.

When time/money are limited, and you can only do one thing, then obviously it's better to write the code rather than the documentation. But then you get what you pay for, which is probably going to be about half of what you really need.

  • Comment on Re: Programming *is* much more than "just writing code".

Replies are listed 'Best First'.
parallel structures are necessary
by doom (Deacon) on May 09, 2007 at 03:37 UTC

    In general, I'm afraid that this piece stikes me as an extended rationalization for being lazy about documentation and writing uncommented code... my personal experience is that if the programmer is under the delusion that the code is "self-documenting" you might as well throw it away and re-write it than attempt to figure out what's going on with it.

    One of the strengths of the perl programming culture is that so many of it's programmers are also fluent in English, and have no problem with writing comments, pod, web pages, articles, books, etc... One of my slogans these days is that "perl is the best documented language in history". If this approach bothers you, maybe you should be looking into a language with a culture that's more suspicious of words.

    BrowserUk wrote:

    One of the high priority goals in programming is the removal/avoidance of codependencies. We avoid using parallel data structures (eg.parallel arrays), because it becomes a nightmare to maintain those parallel arrays in synchronisation as algorithms and projects evolve. One of the key attributes of well designed classes (and other abstractions), is that they are as fully independent of their peers as possible. As decoupled as is possible to achieve.

    This is a clever line of argument, but I don't think it applies to the subject at hand. Nearly every workable methodology for verifying the correctness of code involves comparisons between multiple implementations of the logic: the code isn't complete without documentation (and specs?), and these days most of us would say that it isn't complete without automated tests.

    Note that automated tests have the same problems you're complaining about with comments and documentation: when you make changes it's likely you're going to need to make changes in all of these roughly-parallel structures: code, comments, docs and tests.

    (Update: Fixed attribution of quote to BrowserUk.)

      In general, I'm afraid that this piece stikes me as an extended rationalization for being lazy about documentation and writing uncommented code...

      Sorry, but that first sentence indicates that you have not read what I wrote, but rather skimmed a few bits and reached a conclusion based upon what you think I probably wrote. Eg.

      Comments are not, and should not be, documentation

      Documentation of code is vitally important for successful, ongoing projects, but comments are not documentation.

      I have no problem with you holding a different opinion to myself, but don't put words in my mouth, or draw concusions based upon things I haven't said, much less things I specifically and deliberately already countered.

      Eg.2

      I (BrowserUk) wrote the article, but you've addressed your reply, and attributed my words to graff. If your comments and documentation are as good, you are welcome to them :)


      Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
      "Science is about questioning the status quo. Questioning authority".
      In the absence of evidence, opinion is indistinguishable from prejudice.
        In general, I'm afraid that this piece stikes me as an extended rationalization for being lazy about documentation and writing uncommented code...
        Sorry, but that first sentence indicates that you have not read what I wrote, but rather skimmed a few bits and reached a conclusion based upon what you think I probably wrote.

        I'll plead guilty to trying to intuit what's going on in your head, based on this long and rather strange essay that keeps harping on how words are slippery and difficult and have little place in the pure, pristine world of code.

        To go even further, I think you're someone on a quest for absolute certainty and perfect mathematical order, and I suggest that this has little to do with the world of programming, which is a collaborative effort among human beings.

        Documentation of code is vitally important for successful, ongoing projects,
        Correct me if I'm wrong, but isn't this the first place where you've said this? (( Actually, I am wrong: it's a line from the original essay. ))

        I have no problem with you holding a different opinion to myself,

        So you're not the guy who keeps initially down-voting everything I say in this thread?

        I (BrowserUk) wrote the article, but you've addressed your reply, and attributed my words to graff.
        Fixed. My apologies. There's a reason for the threading glitch (I deleted some material commenting on graffs remarks), but it's not worth going into.

        If your comments and documentation are as good, you are welcome to them :)
        Well you know, "Love the truth but pardon error."

      Comments and docs are issues. But with automated tests, you have to treat them as the running specs of the system. If you change the specs, then you have to change the test cases, and only then, can you change the code to conform to the tests again. In fact, you should never be able to successfully compile your entire project if a test fails. That way the test serve its purpose and it never becomes out of sync.
Re^2: Programming *is* much more than "just writing code".
by BrowserUk (Pope) on May 09, 2007 at 05:48 UTC
    Are you talking about Perl here?

    Yes.

    Are you saying that using POD in perl code is wrong in some way?

    It depends, but essentially: yes.

    Firstly, I am not a fan of POD-- leastwise, not in it's current Perl 5 form--but that's a different issue.

    Secondly, there are many forms of documentation. Comments are (should be) explicitly confined to annotating the code. That is, this particular piece of code, in this file, Preferably on this line. Anything more than this should be dealt with in documentation--somewhere else.

    At the very minimum, documentation should be moved to the bottom of the source file. Interleaving it with the code, detracts from the code in ways that go far beyond just interrupting the programmers overview of the code. It also creates dependencies.

    I cannot agree with that.

    Fair enough.

    (And just where should the documentation be?)

    In a separate file with the same name as the source file but with a different extension. That is, the unit documentation.

    System documentation should exist at the system development directory structure.

    Okay, programming is hard, and writing proper documentation is at least as hard -- often harder: striking the right balance of natural language coherence and logical/procedural accuracy is really another form of the common tasks in programming: problem-solving, puzzle-wrestling, optimizing, getting things into the right operational sequence, working out the best way to refer to things, and so on.

    Sorry to be pedantic, but my meditation was addressed to comments, not documentation. and as I said: Comments are not (and should not be) documentation.

    Simplifying, for the purposes of discussion, some questions to ask when deciding what is comment and what is documentation are:

    • Would this comment be useful to anyone other than another programmer working on this piece of code?
    • Would this comment have any meaning to anyone, in the absence of the code?
    • If this code is ported to another language, would this comment still make sense? /li>

    If the answer to any of these questions is yes, then that comment is not a comment, but documentation. As such, it should be a part of the documentation set, not tucked away in a comment where it will never be seen outside of the source file.

    (Let's face it, every higher-level programming language is really a sort of subset or reduced adaptation of a human language, designed to make control of computers possible for a wider range of humans, and easier for the ones who really understand the machines. Comparing this to mathematics, chemistry, etc, is disingenuous --

    Sorry, but I strongly disagree that it is disingenuous to compare these notations.

    people in those fields need text books, in a human language that they know, in order to learn the symbols and the syntax for combining them. And that's a lot of work!)

    And programmers do not?. They need text books (or their electronic equivalents), to learn how to program.

    So doing both the code and the documentation -- and maintaining both of them to keep them in sync -- is really hard. But that's a lousy reason for not doing it, and based on experience,

    Again, I am not questioning the need for, nor resisting doing, documentation. I am saying that comments -- # words more words etc. is the wrong place for documentation.

    I tend to believe that the code is easier to write (and to get right more quickly) when the documentation has been written first, and is as clear and unambiguous as the code needs to be. What I mean is: the coding is less work when the documentation is done first.

    I totally agree with you, but writing documentation in comment cards is wrong.

    An added nice feature about that, when you're able to do it, is that you can show the docs to people who don't know how to program (e.g. a customer or sponsor), and assuming you are dealing with people who know how to use the same human language that you are using, they can understand it, react to it, make suggestions for improvements, and so on. Even though the population proficient in any given human language is "limited", it's a lot bigger than the population proficient in a given programming language -- English, French, etc are good for something, even to programmers.

    But not for describing algorithms. It is too imprecise. Too shaded with (mis)interpretable meanings. Too complex and vague.

    And a nice thing about doing it as POD in your Perl script is that it's always right there for you, the programmer, and it's also really easy to present to others, the non-programmers, in a clear, human-readable form.

    If you place your documentation in (for example) POD, that's true, but if you place it in comments, the only way anyone sees it, is if they look in the source file. Again, you are failing to recognise the distinction I make between comments and documentation.

    When time/money are limited, and you can only do one thing, then obviously it's better to write the code rather than the documentation. But then you get what you pay for, which is probably going to be about half of what you really need.

    I find this to be an artificial distinction. I've never yet worked on a commercial project where time and money were not limited.

    I also think that no plan survives first contact with the enemy. That is to say, documentation written at a level that prescribes the implementation of any given subroutine, function or class, in advance of the first attempt to implement it, is usually so far from reality that it is next to useless either in writing that first implementation, or for maintaining it once the code is working. Without serious work, it rarely if ever reflects the realities of the implementation.

    But in any case, you are still confusing my meditation on comments with something relating to documentation. Nothing I said precludes, nor denigrates the writing of documentation. Indeed, I said in my meditation that "documentation was vital".

    All I said that related to documentation, is that comments are should not be used for documentation purposes. And that source files are not the right place for it. I will concede that, if you think that embedding documentation in code (POD) is a useful concept, then keeping that documentation in the same file as the source has some merit. Not much, but some.

    However, I strongly feel that the practice of interleaving code and documentation is a bad one. If you must keep it in the same source file, at least keep it all together. Preferably at bottom after the __END__ mark, though that is impossible if the code uses a __DATA__ section.

    Personally, I think that POD has it backward. If you want to go with the idea of containing code and documentation within the same file, I much prefer the Literate Programming concept of having the interpreter/compiler simply ignore everything outside of some equivalent of <code></code> blocks, as is used by Haskell, D and others. This allows you to write the documentation first, in whatever markup it adopted by the project, and using the full power of that chosen markup.


    Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
    "Science is about questioning the status quo. Questioning authority".
    In the absence of evidence, opinion is indistinguishable from prejudice.

      At the very minimum, documentation should be moved to the bottom of the source file. Interleaving it with the code, detracts from the code in ways that go far beyond just interrupting the programmers overview of the code.

      You're in agreement with Damien Conway on this, but myself I think interspersed pod-style has some strong DRY advantages. Most subs require some verbal description to go with them, and there's some overlap between what you need to say for the benefit of a maintenance programmer working on your code and a client programmer interested in using your code, and it's not at all a bad idea to put that inside an "=item" that goes with the sub. (And I would hope that it is obvious that remarks that are only of interest to a maintenence programmer should be confined to comments.)


      It also creates dependencies.

      The dependencies between the documentation and the code do not go away if you move the documentation elsewhere.


      Personally, I think that POD has it backward. If you want to go with the idea of containing code and documentation within the same file, I much prefer the Literate Programming concept of having the interpreter/compiler simply ignore everything outside of some equivalent of , blocks, as is used by Haskell, D and others. This allows you to write the documentation first, in whatever markup it adopted by the project, and using the full power of that chosen markup.

      I'm once again, having trouble figuring out what you're getting at here. Nothing about the interspersed pod style I'm arguing for prevents you from writing the documentation first, and in fact I often work that way. Of course, if you use this style you have to present the code in the same order that you want it to appear in the documentation, and that's a problem that would go away in a true "literate programming" language.

      By the way: you do understand that you can embed other markup inside of pod if you want to, right? From perlpod:

      =begin html <hr> <img src="thang.png"> <p> This is a raw HTML paragraph </p> =end html


      If you must keep it in the same source file, at least keep it all together. Preferably at bottom after the __END__ mark, though that is impossible if the code uses a __DATA__ section.

      Actually, you should get out of the habit of using __END__ at all: it breaks mod_perl code.

      I agree with you completely, BrowserUK, but especially with two points (my paraphrasing):
      • The best course of action in examining code is to strip out everything but code and format it consistently.
      • Documentation should be detailed and use every tool we humans have come up with for enhancing readability.
      I, too, am a fan of Literate Programming, though I have yet to find the right tool to give me both views of a project. We should be able to switch between pure-code view and documentation view at will, without the messy comment-stripping and PerlTidy steps in the middle. Even better, I'd like three views: pure code, syntax-highlighting with hyperlinked definitions and where-used lists, and documentation view with full text enhancement. Ed Ream's Leo is a step in the right direction, but it isn't all the way there. Mindmaps have documentation advantages, too, as do some CASE environments. I think doxygen is also a great example of the direction we should be heading in this arena. The Xerox PARC Star environment (also Smalltalk/V, Squeak, etc.) with classes and clickable browsers also had excellent usability features, although Smalltalk, the language, was a syntactic mess.

      We have powerful computers these days, with incredibly powerful graphics. I grew up with 7-segment displays and a hex keypad, and I spent much of the first half of my career burning EPROMS on microcontrollers. I have come to believe that, no matter what the ultimate target, fancy IDEs that enhance the programming (and debugging) experience are essential to rapid and effective code development. The need grows exponentially more urgent as teams expand and the underlying hardware, OS, and system interfaces become more complex and critical.

      Don Wilde
      "There's more than one level to any answer."

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://614287]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others examining the Monastery: (5)
As of 2020-10-27 20:40 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    My favourite web site is:












    Results (258 votes). Check out past polls.

    Notices?