Dismiss Notice
Join Physics Forums Today!
The friendliest, high quality science and math community on the planet! Everyone who loves science is here!

Software Explanation Document !

  1. Apr 29, 2008 #1
    In software maintenance, I have noticed that very few organizations and companies publish a precise well written Software Explanation Document to explain exactly and in a very well written way how thousand lines program work.

    It is amazing that of all the documents that are written, none of them tell a programmer exactly how the lines of code really work, as if the real working of the code is intentionally left as guess work. I have seen this in very top class professional programs, I bet even NASA and military software programs never really have a Software Explanation Document that can tell a maintenance programmer exactly how the entire program works and all the details necessary to then modify it. Why is this so ? Software maintenance costs a huge amount of money and time and there is no real quality assurance possible without a complete and very detailed written explanation of how a program works.

    Actually if an organization needs a program, the only real thing that must be and should be delivered, is only the Software Explanation Document. If any programmer reading and studying this documnet cannot understand it well, then the software can be considered as not having been delivered at all and should not even be paid for until there is this precise document to back it up.

    How is it that after decades of software research companies simply don't deliver the most important single document that a maintenance group needs ? Aside from the fact that the program can be studied and all the design decisions can be judged upon giving the buying organization its money's worth and the power to really judge a program.

    I find it incredible that in this day and age almost all companies still have to waste an enormous amount of time to figure out how programs work, when it could have been forced upon from the very beginning. Software "engineering" still has a long way to go until a Software Explanation Document doesn't become the real PRODUCT that should be delivered.
  2. jcsd
  3. Apr 29, 2008 #2
    Actually to be even more precise the name of the document should be:

    PROGRAM EXPLANATION DOCUMENT so as to pinpoint down exactly what is really needed to understand and eventually change a program written previously by another group.

    I find it very primitive that the knowledge embedded in programs must be hidden, must belong to those who wrote the program, and when they are gone the embedded knowledge goes away too. In some cases even the original programmer can't remember what on earth he did and how the program works after some time!

    I think the "comments" method of writing comments next to lines is another very primitive system, that was maybe ok a couple of decades ago (and probably not even then) but not today. Each line, each group of lines, all the design decisions, all the relevant information must be explicitly written out, not short cutted like in comments, not guessed out, but must be explained with the upmost precision. This is the only real tool that software and software engineering have to increase productivity and to start progressing like other engineering disciplines have.
  4. Apr 30, 2008 #3
    Real Programmers don't use comments.

    If it was hard to write, it should be hard to read.

    My favourite was an assembler program with the solitary comment "START"...
  5. Apr 30, 2008 #4


    User Avatar
    Science Advisor
    Homework Helper

    Real Programmers don't use compilers.
    OCO (object code only) is the way to go.

    [Rant]Salesmen have been pushing documentation snake-oil since the dawn of computing.
    The problem is that if your PROGRAM EXPLANATION DOCUMENT did what you wanted it to, then you could just compile that. It would be the program. [/rant]
  6. Apr 30, 2008 #5


    User Avatar
    Science Advisor

    That's a load of crap. One of the first things I learned in my very first computer science class was the importance of proper comments.

    What if the programmer got hit by a taxi after he finished his uncommented program which was very complicated to create for whatever reason and another programmer had to come in and try and figure out what he was thinking? A lot of wasted time which leads to wasted money.

    Granted the comments must be meaningful and are not needed for obvious things.

  7. Apr 30, 2008 #6


    User Avatar
    Gold Member

    I always commented source code. It didn't get into the compiled distributed applications, but comments were always in the original code. This make it possible for some one other than myself (or even myself, after a time) to make needed modifications without parsing all the code to find out where the changes needed to be made.
  8. May 1, 2008 #7
    Crap it may well be... it was an interesting program to maintain, since everyone who knew how it worked had left.

    I was the guy who had to modify it to do what I wanted it to do...

    You've not met many Real Programmers then, have you... :biggrin:

    Then again, I had the source, it's even more difficult to modify the executable by patching the binary.
Share this great discussion with others via Reddit, Google+, Twitter, or Facebook