Even if you do design clean modular code and document it, you’re getting a question a year from now about how it works, or someone just duct tapes on top of it.
I’ve even experienced this in the 3D printing community, where I design a highly parametric model and put lots of effort into making all of the major dimensions and qualities parameterized and dynamically adjustable, with lots of bounds checking and value clamping, with all the parameters at the top of my scad file with comments explaining what each variable does.
And then someone comes along to remix my model, says I don’t want to install openscad, and just scales the entire output stl to change the dimensions, squashing all the features of the model in the process (instead of having the size gracefully adjust with all the features moving around to account), and leaving anybody starting from their work with a hard to remix mesh with no parameters.
The ‘document’ part also seems to be insanely hit-or-miss from my amateur experience. Self-documenting design/code is… well, not. Auto-generated documentation is also usually just as bad IMO. Producing good documentation really is a skill in and of itself.
Also small personal opinion: If your abstraction layers or algorithms are based off a technical concept, you should probably attribute that concept and provide links to further research, to eliminate future ambiguity or in case your reader lacks that background. Future you will probably thank you and anyone like me who immediately gets lost in jargon soup will also be thankful.
This is so true.
Even if you do design clean modular code and document it, you’re getting a question a year from now about how it works, or someone just duct tapes on top of it.
I’ve even experienced this in the 3D printing community, where I design a highly parametric model and put lots of effort into making all of the major dimensions and qualities parameterized and dynamically adjustable, with lots of bounds checking and value clamping, with all the parameters at the top of my scad file with comments explaining what each variable does.
And then someone comes along to remix my model, says I don’t want to install openscad, and just scales the entire output stl to change the dimensions, squashing all the features of the model in the process (instead of having the size gracefully adjust with all the features moving around to account), and leaving anybody starting from their work with a hard to remix mesh with no parameters.
The ‘document’ part also seems to be insanely hit-or-miss from my amateur experience. Self-documenting design/code is… well, not. Auto-generated documentation is also usually just as bad IMO. Producing good documentation really is a skill in and of itself.
Also small personal opinion: If your abstraction layers or algorithms are based off a technical concept, you should probably attribute that concept and provide links to further research, to eliminate future ambiguity or in case your reader lacks that background. Future you will probably thank you and anyone like me who immediately gets lost in jargon soup will also be thankful.