version
The documentation is there to tell you what you thought you were doing
when you wrote that.
It's also there to help people who dive into your code when they get
error messages just what is happening. It is also there for YOU to
figure out what is happening.
I develop code and documentation in parallel. Frequently, documentation
helps me find bugs (or need for features) in code that I've written.
Unless you have a perfect memory (and I don't), you will find the need
for documentation somewhere around 3 to 6 months after you think the
project is done.
Harvey
On 8/22/2024 8:06 PM, Kevin Cole via Discuss wrote:
On Thu, Aug 22, 2024 at 6:37 PM Jon Bondy jon@jonbondy.com wrote:
An official release requires documentation. Altering that once,
rather
than weekly or monthly, may take less time. I am not an OpenSCAD
developer, but there may be reasons to not do an official release
very
often.
For me, documentation has always been an integral part of the code.
Even if it's in a separate file. This is what I keep stressing with
students: If you make a change to the behavior of code, make a change
to the corresponding documentation. If you're changing the code so
often that you cannot keep up, don't recommend your code in flux to
anyone. Small incremental changes that get stabilized and documented
and released are better than trying to create a masterpiece / opus
that will still be unfinished at the time of your death.
(A development version should only be for developers and testers,
not for people who actually want to use your code in production. Sure,
the testers may do interesting things with new features, but don't
make all users dependent on undocumented features.)
Like many here, I use 2021.01 and am pretty happy with it. But when I
keep reading questions about features mentioned on the mailing list
that don't exist in 2021.01, I wonder if it's time for a list for
developers and a list for users. If the only way I can learn something
from the mailing list is to set up a cron job to install nightly, then
the list isn't a general discussion list.
OpenSCAD mailing list
To unsubscribe send an email to discuss-leave@lists.openscad.org
I agree 100%. Documentation is not only useful for users that you give the finished/release version to, but for yourself. I have had many times in which I go back to work on a project and if not for the documentation, both formal and just simple comments in the code, it probably would have taken me 10x or more to update and/or fix it. Some editors also display info in comments when you hover over the variable, module, function, etc., which can make the development process much easier. When I first became a developer, I won't deny the fact that I didn't always recognize the importance of documentation & comments, but now I wonder how I ever managed to survive without them. Documenting & commenting your code is one of the best habits a developer can have. When it comes to version numbers, it probably depends on whether you are developing for personal use (like a simple hobby that you work on independently) or for a large commercial business where it will be worked on & used by many people. I don't normally use version numbers, because I don't share my code with other people (I'm just an independent hobbyist), and if I make major changes in the functionality, it's usually big enough that it should just be a different project altogether. So do what you want, but to me, not using documentation & comments is like a salesman or bank not using file folders (ok, maybe that's a bad example with electronic recordkeeping, but you get the idea). Good luck!
Nathan Sokalski
njsokalski@hotmail.commailto:njsokalski@hotmail.com
From: Kevin Cole via Discuss discuss@lists.openscad.org
Sent: Thursday, August 22, 2024 8:06 PM
To: Jon Bondy jon@jonbondy.com
Cc: OpenSCAD general discussion Mailing-list discuss@lists.openscad.org; Kevin Cole dc.loco@gmail.com
Subject: [OpenSCAD] Re: version
On Thu, Aug 22, 2024 at 6:37 PM Jon Bondy <jon@jonbondy.commailto:jon@jonbondy.com> wrote:
An official release requires documentation. Altering that once, rather
than weekly or monthly, may take less time. I am not an OpenSCAD
developer, but there may be reasons to not do an official release very
often.
For me, documentation has always been an integral part of the code. Even if it's in a separate file. This is what I keep stressing with students: If you make a change to the behavior of code, make a change to the corresponding documentation. If you're changing the code so often that you cannot keep up, don't recommend your code in flux to anyone. Small incremental changes that get stabilized and documented and released are better than trying to create a masterpiece / opus that will still be unfinished at the time of your death.
(A development version should only be for developers and testers, not for people who actually want to use your code in production. Sure, the testers may do interesting things with new features, but don't make all users dependent on undocumented features.)
Like many here, I use 2021.01 and am pretty happy with it. But when I keep reading questions about features mentioned on the mailing list that don't exist in 2021.01, I wonder if it's time for a list for developers and a list for users. If the only way I can learn something from the mailing list is to set up a cron job to install nightly, then the list isn't a general discussion list.