Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: Headless build [was Re: [cdt-dev] RIP Wascana, Build System discussion]

Alex Blewitt wrote:
For me too, trying to figure out how to add a -framework flag to the linker was an exercise in frustration itself and at one point, I was writing my own wizard with a new project by unzipping a template project with all the metafiles set up correctly because the documentation was next to useless. Many of the APIs are marked EXPERIMENTAL and appear to have been that way for a while; and much documentation on e.g. build was written against 3.0 with a "migration guide" to 4.0. So I have to learn an antique tech to then learn the diffs of that tech to just get to one version behind?

It's like into tests. Once one starts to fall, you don't notice when the second starts to fall, and before you know it, you're facing a project whose unit tests are dead weight. Then, of course, you feel like there's no point in writing new tests because there would be no alert if it started to fail.

This is also known as the "Broken Windows"-theory:

Does documentation help those who already know how it works? No, they've grown up with the stuff - and probably wrote half of it.

Another problem with is even harder to handle is the fact that it is difficult for developers who knows how everything works to write documentation for people who don't. This usually causes the documentation to contain "white spots": things which the developer doesn't even realize needs documenting.

For JDT type projects, half of the people probably work in the next office to you, and you can ask them over lunch. But what happens when that project is mothballed or put into maintenance mode? People get reassigned and the knowledge is lost.

Code can certainly evolve faster than documentation. That doesn't necessarily mean it should. But for projects with longevity, particularly those where it's important to encourage growth over time within a communtiy, documentation is the torch that gets passed from one generation to the next. Code without unit tests is deemed less valuable than code with. The same should be true of features without documentation.

It should be, yes.


Back to the top