If you're in a programming shop then maybe that's a reasonable assumption. However, I work with a bunch of Telecommuncations engineers. One of the guys is pretty good with MS-Access and VB Script but I'm the only person in the group that knows anything about Perl. And I am not a programmer. The last time I did any serious programming it was on an IBM 360 in PL/1 with punch cards. I'm a general computer/network geek that got saddled with the programming tasks because I'm the resident "Data Guy". In a situation like mine, it's NOT reasonable to assume that the person who comes in behind me one day will know any more Perl that I did when I bought the Perl Bookshelf CD lo these many months ago.
When my boss asked me to take this on, the primary focus was to update some scripts that had been written by one of the IT guys who had since left the company. Trying to figure out what he was doing was next to impossible since he had written the code assuming that he would be the only person to ever maintain it - or so I assume since he didn't indent, didn't use whitespace and didn't comment anything...ever. I had to figure out what groups of programs to look at based on their file names and when they ran - "This output file has a creation time of 20:38 so I'm looking for a program that runs sometime before that."
I have to agree that comments and documentation aren't supposed to be a tutorial but it's nice when a) they exist at all and b) they are comprehensive enough that you can follow the general flow of the program without having to read the code.
Just my opinion...
Jack | [reply] |
I think its reasonable to assume that the person who has to maintain your code is at least an average Perl programmer. The purpose of coding, commenting, and documentation isn’t to teach Perl to beginners.
That's making a vastly unwarranted assumption.
Look at the most junior person who is (not "should be, if only my boss would listen", but who is) assigned to maintain perl code: and always ensure that they will be able to read what you write.
An expert can always decipher simple code; a novice often can't decipher "clever code". Programmer time is expensive: don't waste it. Even if it takes 10% longer to simplify your code style (and it probably doesn't, if you're good): it's probably just plain cheaper to write code maintainable by the novice, unless it's going to incur a business cost in terms of performance (unlikely, but possible in some cases). Remember, senior programmer time is expensive: anything that someone lower paid can do is (a) work you're not tied up with, and (b) puts available resources to work productively.
In short, do what's right for your company: not what fits your preconceptions of what a programmer "should be". They're often not the same thing at all...
| [reply] |
I think its reasonable to assume that the person who has to maintain your code is at least an average Perl programmer. The purpose of coding, commenting, and documentation isn’t to teach Perl to beginners.
Not according to every anecdote I've run across, including those I've been personally involved in. When I was contracting at a large outsourcing firm, my maintenance tasks included SAS, PL/1, and COBOL code. I had never even seen code in any of these before. A much better assumption than assuming the person who has to maintain your code is an average Perl programmer is assuming that she|he will be trying to make sense out of code with Learning Perl in one hand and a jar of ibuprofen in the other
emc
" The most likely way for the world to be destroyed, most experts agree, is by accident. That's where we come in; we're computer professionals. We cause accidents." —Nathaniel S. Borenstein
| [reply] |