Slashdot Mirror
The Code Is The Design
danielread writes "In 1992 C++ Journal published an essay by Jack W. Reeves called 'What Is Software Design?' Many credit this essay as being the first published instance of assertions such as 'programming is not about building software; programming is about designing software' and 'it is cheaper and simpler to just build the design and test it than to do anything else'. developer.* Magazine has republished this groundbreaking essay, plus two previously unpublished essays, under the title Code as Design: Three Essays by Jack W. Reeves."
"The initial hump is steeper, but the total area under the work curve, over the product lifecycle, is much less."
Excepting that everytime you replicate the code in alternate forms you are creating something that has to be kept synced, and unless all these things are kept in perfect sync they are more deception than aid. There should only be one copy of the algorithm because it is gospel, and it is the code not the docs.
If you have reams of design docs, requirement docs, and feature definitions, you are going to have a massive tarbaby, a tool for wrecking your schedule, inflating cost, wasting time, an incentive to never change anything because you have 5 places you have to go back and update and basicly say the same thing in 5 different ways.
Comments in code are priceless when there is something that is not obvious that needs to be explained. They are a complete waste of time and space if you just say the same thing the code already says but differently. 90% of the time careful class hierarchy, file organization and variable naming do the job and comments are a complete waste of time and space and again you are just doing the same thing twice. But when you really need to explain an intricacy of a less than obvious algorithm you should write a book, in comments next to the algorithm, not in some doc far, far away. So bottomline is comments are priceless when you put the right comments in the right places, gratuitous spewing of comments just for the sake of saying your code is commented is not a good thing.
It is very true an object oriented language used by someone who has a minimal clue of how to write object oriented code is going to be vastly easier for other programmers to read, pick up and use. Sure you can accomplish the same end in C but it will be ugly, tedious and inadequate by comparison. God bless GTK, and lord knows I've used it enough but developing a UI toolkit in C was not a good idea.
All that said there are places where you do have to do the reams of documents. If you are writing code that is an API for someone else you must properly document the API. You will be way ahead of the game if you use one of the document tools that builds the API doc from the code and comments automaticly so you know that the API is always in sync automaticly and not through laborious manual labor.
Part of being a good programmer is maximizing efficiency and wasting massive time syncing multiple sets of docs with code is not efficiency.
When you are coding something for someone elses need, then THEY should absolutely document as best the can and in as much detail as they can their requirements, and then the programmer(s) should read those and have meticulous discussions with the client on every gray area, or where the asked for something the probably didn't actually want because there is a better way. This is an essential form of communication and unavoidable.
To put it another way the extent to which you document code is almost entirely a function of the audience around the code. If its buried inside a module that people are going to just use and rarely ever care about, then you are completely wasting your time whipping it to death with reams of documents. You are wasting time that could be better spent developing useful code. If you are writing code that is an API for others it would be criminal on your part to not document the API in one form or another, but most of the people using your API don't need or want massive documents on every gory detail of what is underneath the API, they just need to know that the stuff underneath reliably does what the API says it does.
@de_machina