A solo programmer needs good written communication skills. Without them there will be no decent documentation. So, working solo does not give an exempt from communicating with other people.
Also, a good team leader can replace some of the personal deficiencies of group members, makes the quiet talk and the talkative shut up. (And a bad team leader can make the life feel like something written by Dante.)
- Ville
-- Ville Voipio, Dr.Tech., M.Sc. (EE)
There is a balance to be struck here. In most modern companies there is indeed a great concern with the bottom line. That's because those who are less concerned with the bottom line are no longer employing anyone because they are no longer in business.
This is particularly the case for small compnaies who can't amortize the cost of documentation, or documentation controlling people, over a large number of employees. In a small company, you have to keep the money coming in to pay the engineers, and rarely are customers willing to pay for documentation as a direct chargeable cost. This means that as soon as the engineers have finished working on something and it gets shipped, they have to move on. Full stop (or period, depending where you come from). Otherwise there is nothing to pay them with.
Also there's a question of cost-effectivness. Often after a project is finished and some time in the field has passed, noone will visit the code for a long time, and perhaps never. Is it worth spending 100 hours documenting code now that may never be revisited? Is it worth spending that 100 hours documenting code that may be revisited, but it'll only take the poor sucker 50 hours later to figure out how the particular bit of code that's causing a problem works anyway? It's easy to look at some old code and curse the lack of documentation when it's you that's got to do it, but is it really costing the company more to have you do that than it would have to document it "properly" in the first place?
As I said at the beginning, there is a balance to be struck. At the end of the day, someone has to pay for any documentation, and that someone has to be the customer, and they are rarely willing to pay for code-level documentation. That might not be ideal, but it's the way it works. Anyway, look at it pragmatically. As an engineer what would you rather be doing, engineering or documentation?
As a case in point, we almost never write anything external to the source code as documentation. We use the file headers for an overview if it's appropriate, and function header comments where appropriate and a running commentry in the function body if that's appropriate. We do format the comments for Doxygen, though, these days. That way, code documentation doesn't require any special effort, and is written as part of the "flow of thought" as modules are created, and it's relatively easy to keep it up to date with the actual state of the code as things change. It wouldn't satisfy NASA, but our customers don't pay NASA rates and we're still in profit.
-- Trevor Barton
Indeed, actually, every one try to reduce the (famous) "time to market". It's easy to speed up a project if the documentation process is not done.
I don't agree with you on this point : it's the best way to create unmaintainable code and buggy software :
- many globals and border effects
- tricky patches everywhere
- no logical architecture/structure
I had to port an old program made like this (10 years old), it was a real nightmare ! Even several years after the initial release, there were still nasty bugs hanging around (mostly border effects).
A good initial analysis (generaly with a bit of documentation) help a lot to produce a good architecture. Software engineering is not just "coding" ! ("coding" is more and more often done in the 3rd world country actually...)
Regards Emmanuel
In my small employer, I've managed to show my bosses that the lack of documentation was costing us my time in technical support and training, and the sales guy wanted nice manuals he can show people to make them feel good, so I've been let loose on a documentation project. Yay! Alas, the sales guy is always wanting me to reword bits of it, or use pretty fonts, or churn out millions of screenshots and diagrams to make it look glitzy - I'm more concerned about it covering everything and being easily readable :-/
But this is user documentation, not code documentation. Currently, I am the code documentation; I'm always working on this software so I'm not likely to forget much (although it is now large enough that I have to spend time refreshing my memory when I work on parts of it that have lain fallow for a while now...). So I don't think I'll have much luck pressing to be allowed to write code documentation for a while - at least, not until I look like I might want to leave the company or anything like that...
ABS
... snip ...
IMO most of what you describe should be notes or comments in the master drawings or sources. It does not belong in what I consider to be 'user documentation', and probably should never be separated into easily lost or ill-maintained separate verbiage.
--
Chuck F (cbfalconer@yahoo.com) (cbfalconer@worldnet.att.net)
Available for consulting/temporary embedded and systems.
USE worldnet address!
Heck, it's often difficult to remember (let alone describe) my own thought processes when looking at code I'd written six months earlier. The process:
- "What was I thinking?" - [edit, compile link, test, (sound of code breaking)] - "Oh yeah..."
;-)
Regards,
-=Dave
-- Change is inevitable, progress is not.
You are right, bad habits have the habit of concentrating into one place. Sometimes it is difficult to tell which problem is the root cause.
- Ville
-- Ville Voipio, Dr.Tech., M.Sc. (EE)
I am a hw guy, most of the time. I always try to make a few papers about each circuit, as I tend to forget things even myself. In sw a lot can (and must) be done in the source comments. However, I still feel there is a need for some documentation outside of that, especially in larger projects. What is behind this module division? Why were the sw interfaces chosen as they are?
User documentation is an entirely different story. It requires a lot of non-technical skills, as well. I think the user documentation should be written by technically skilled writers who have not been writing code or designing hw in the project. That gives them a more customer-like attitude. (Not marketing, not the hw/sw designers.)
"Why did you do it this way? There is no way to explain this clearly in the manual!" "Umm, it's crystal clear, it took me only seven fortnights to figure it out."
And, of course, this depends on your customers. If you sell pieces of software to other programmers, you can use very technical descriptions. If you are selling real things to end-users, they cannot be expected to be specialists on your field.
- Ville
-- Ville Voipio, Dr.Tech., M.Sc. (EE)
I had a guy working for me who used to crank out hundreds of lines of code
- in a day or two - without a single comment. When I challenged him on this he would respond: "but my coding style is so obvious it's practically self commenting..." I should have put him to death of course, but he was just so damned brilliant.
Bob
Well that's design, which is a different thing to documentation. Design can be as little as a discussion between team members to someone working on a written design and giving it to everyone else to a multi-volume spec from the customer. I wasn't talking about the design process, though.
I'm talking here about documentation of the implementation, and my point is that it's important to do that in a way that doesn't impinge on the costs of producing the software, and also in a way that doesn't involve engineers doing things that they have neither the time or the temperament (sp?) to do. Keeping it simple, local (ie inline with the code) and automated (Doxygen) is the only way you realistically have a chance of keeping it relevant and up to date.
-- Trevor Barton
Yeah, I was talking specifically about code documentation. User documentation is neither use nor ornament to the person trying to maintain the code later (almost). It's also something the customer is likely to want to pay for, but if she doesn't it matters little as far as the project implementation goes.
I was also putting more of an emphasis on single user projects, for example systems specific to one customer. There the choice of user documentation is more down to the customer. I would agree, however, that if you are writing software to be sold to a large number of customers there might be more reason to take the burden of user documentation on yourself (as a company), but of course the cost is then amortized across the entire user base. It's all a matter of balance, but at the end of the day it's not going to get done if it's a net cost to the company.
-- Trevor Barton
In principle, of course, code is self documenting. After all, the computer has no problem in reading it, understanding it, and doing exactly what the code tells it to do! It's just our undertanding of the programming language is not as good as the computer's, so we need all the extra verbiage around the code to try to explain what the code means. If we spoke native C or whatever there'd be no issue!
Does anyone produce compilers where the language keywords are in languages other than English?
pour (i = 0; i < 10; i++) { ecritf("%d", i); } sortie(0)
I've come across code in which variable names and comments were in French and the C in English, which just looks silly ;-)
-- Trevor Barton
One use of user documentation for me as a developer is that I can use it as a spec, and feel freer to change undocumented behaviour ;-)
I agree! I wasn't disagreeing, just giving a kind of case study of how I'd managed to show management that some documentation was worth doing, while some wasn't.
ABS
I began programming in Assembler - machine language actually now that I think about it, and I was taught by my boss at that time to comment my code such that a non-programmer could scan through it and get the gist of what I was up to. I still think that is a good underlying premise for documenting code.
Bob
ecritf("%d", i); //LOL ;)
I strongly hope that nobody ever did anything as braindead as that for the embedded market. People in this field should definitely know better. And of course, for C programs, you could always do that yourself using the preprocessor, if you really want to. But honestly I think nobody ever should unless they're writing a submission for the IOCCC.
But there _have_, of course ;-(, been attempts in that direction. E.g. Microsoft "WordBasic", the internal scripting language of WinWord
6.0, had the entire standard library available in the products installation language --- whereas they at least had the decency to let the language keywoards alone, IIRC.That obviously caused a major maintenance desaster when they saw the error of their ways only one release further down the road (VBA, as of Word 97), and everything had to be translated _twice_: first from internationalized Word Basic to English Word Basic, then from there to VBA.
-- Hans-Bernhard Broeker (broeker@physik.rwth-aachen.de) Even if all the snow were burnt, ashes would remain.
Creating good documentation usually has a beneficial effect on the bottom line. This is not always immediately obvious to those that do the accounting of such matters on a short term basis (most accountants) but is seen when properly considered over the life of the product (the benefits are in reduced maintenance costs).
[X]
NASA and others similar clients tend to insist on sight of the document package before you even buy the first hardware component and certainly before you lay the first bit of production code.
I also tend to comment in the source code headers to indicate the intent of each function and maybe the reasoning behind the approach. However, I do not cut any code to meet the intent implied in the comments until such time as a significant proportion of the system is commented this way and has undergone a review. That way, when I do write the code the requirement for each function is quite solidly thought out and is unlikely to change too much. It is a sort of factoring of the requirements down to sub-routine level. This is not necessarily all top down as sometimes I find it easier to do the middle layers first.
-- ******************************************************************** Paul E. Bennett .................... Forth based HIDECS Consultancy ..... Mob: +44 (0)7811-639972 .........NOW AVAILABLE:- HIDECS COURSE...... Tel: +44 (0)1235-811095 .... see http://www.feabhas.com for details. Going Forth Safely ..... EBA. www.electric-boat-association.org.uk.. ********************************************************************
... snip ...
My memory must be failing. I don't remember working for you :-)
--
Chuck F (cbfalconer@yahoo.com) (cbfalconer@worldnet.att.net)
Available for consulting/temporary embedded and systems.
USE worldnet address!
... snip ...
It has happened, but is a bad idea. The result is totally non-portable, and certainly non-understandable by a non French reading (in the above case) maintainer. Most reasonably intelligent programmers are quite capable of memorizing a 30 to 60 word furrin vocabulary.
--
Chuck F (cbfalconer@yahoo.com) (cbfalconer@worldnet.att.net)
Available for consulting/temporary embedded and systems.
USE worldnet address!
Weirdo.
8-)
It's amazing how strange your own code can look after a break of 6 months or so.
I like writing - I've co-written a book and technically edited two more and don't plan on stopping any time soon :-)
Yes! Until I remember what the mental model I was working with was. Code documentation, of course, could mainly boil down to recording the mental model, then a few extra links between the bits of the mental model and the bits of source that implement it...
ABS
ElectronDepot website is not affiliated with any of the manufacturers or service providers discussed here. All logos and trade names are the property of their respective owners.