Quantcast
Channel: fritzing forum - Latest posts
Viewing all articles
Browse latest Browse all 28182

No schematic or pcb rats nest lines for adapter part

$
0
0

This could get into a religious war with others, but here is my opinion. With nearly 40 years doing programming for context.

RANT ON

For an application / product that has an api (like custom part creation), the documentation is actually part of the product. Missing the information about the rules to follow to use the product is a bug itself. Broken code means an usable app. So does lack of information about the requirements to follow when using it. Some bugs have more or less usable work arounds. Reading the code is a work around for no documentation. It is not a fix or proper alternative. Work arounds do not make either type of bug go away.

A work around that essentially says read the code is of limited usefulness. Even those with the right background are going to need to spend a significant amount of time to be able to use it. About as useful of work around as one that requires specialized knowledge of the internals of the operating system.

There should be some level of documentation before the code is even written. Call is specifications if you like, but what the program is to do better be known before writing the code. When the code is evolving, with no clear pre-defined direction, documentation is even more important. That situation involves a lot of try something, see if it works, back up and try something else. Those paths tried and rejected need to be recorded, to prevent even more wasted time when someone else tries the same failing path.

Code is never truly finished. Given the choice of 100 features that I can not use because there is no information on how to use them, and 50 features that have the documentation to use them, I'll take the 50 plus documentation. If the documentation was being written right along with the code, treated as part of the package being produced, that would probably be more like 80 features. The documentation makes the code easier to write, easier to test.

Extracting usage information by reading the code takes 10 times as long as creating it as the code is written. Doing it afterwards means first learning what the code does, then creating the documentation from that knowledge. Forcing everyone to read the code to get the documentation means that every single person that wants to use those features needs spend that amount of time, for the features they are going to use. Versus the one tenth time needed by the one person writing the code, or better, writing the specifications before the code was written.

That does not mean the programmer needs to produce full detailed, ready to read documentation. It is quite valid to produce very rough content, that is then passed to someone else to clean up and make pretty. With the rough verbiage, it only needs a general knowledge of the application goals, and decent writing skills, to to turn out good documentation for everyone else.

RANT OFF


Viewing all articles
Browse latest Browse all 28182

Trending Articles



<script src="https://jsc.adskeeper.com/r/s/rssing.com.1596347.js" async> </script>