I've been working on a very long shell script that's becoming a mini-application. It is my first script, and continues to grow each week, becoming more and more complex.
I've been asked to document my script, beginning with basic information and then detailing any information about its functionality, in the event of my absence.
My question: Is there some kind of template I can take a look at for how to properly document one's script. I guess the same ideas can be applied for other programming languages, but I've never documented much of anything so I need to know how to effectively communicate the workings of my script to someone else who has no idea what it is.
Any and all suggestions welcome. Microsoft Word, or VI created "readme" file all welcome. (Do I use an outline? Is there an unofficial standard to how everyone else documents their code? Where do I begin?)
This is where coding, "art", and managers all bash heads.
For starters, I would create a header like this
If you are creating a giant script, consider creating functions for larger sections of your code. Put all of the functions at the top, with one-sentence desciptions for each one.
As you are finding out, it can be hard to debug a script, especially since you often end up with loads of variables. If you can, initialize all of the variables right at the top
and put a brief descirption of what it does:
Use meaningful names $REC_CNT, $SUM .. not $VAR or $X
There's a code analysis concept :Halstead volume - it relates the complexity of the vocabulary (number variable names, obfuscated names like $X) to the difficulty of maintaining code and making correct changes. The more variables, the greater the difficulty.
All,
I am looking for a way to improve this small one liner.
one of the files has this kind of format
public func <<<T>(array: , offset: Int) -> { return array.shiftedLeft(by: offset) }
gsed -i '/public func/i /\/\/\public func \n/\/\==mark==public func' tresults in
///public func ... (5 Replies)
Hello All,
I am trying trying to write a shell script that will do a couple things:
1.) Identify any username that logs into the server.
2.) When the user logs out, send them an email detailing
their log in/out times, duration logged in, and what
processes they ran.
Basically,... (3 Replies)
I am programming using C++ and am wondering how to comment my project.
For example, when I declare a class I created a header with some description, then have the declaration stage, which I don't comment. Then when I define the actual functions I will put details about it, what it does,... (2 Replies)
I've been asked to do a high level summary of the cron jobs which run against a number of systems (to understand the potential scope for rewriting some of our core systems)...and was wondering how people have done this in the past.
I've got approx 400 cron entries to go through.
I will have... (2 Replies)