LinuxQuestions.org
Welcome to the most active Linux Forum on the web.
Go Back   LinuxQuestions.org > Forums > Non-*NIX Forums > Programming
User Name
Password
Programming This forum is for all programming questions.
The question does not have to be directly related to Linux and any language is fair game.

Notices


Reply
  Search this Thread
Old 06-23-2018, 02:52 AM   #1
Walt.D
LQ Newbie
 
Registered: Jun 2018
Posts: 1

Rep: Reputation: Disabled
Do You Put Comments In Your Shell Scripts?


I personally don't because I'm the only one in my household that uses linux and the only one that uses the scripts. Since I wrote them, I know what each statement does.

How about you?
 
Old 06-23-2018, 04:39 AM   #2
hydrurga
LQ Guru
 
Registered: Nov 2008
Location: Pictland
Distribution: Linux Mint 19 MATE
Posts: 6,207
Blog Entries: 2

Rep: Reputation: 1978Reputation: 1978Reputation: 1978Reputation: 1978Reputation: 1978Reputation: 1978Reputation: 1978Reputation: 1978Reputation: 1978Reputation: 1978Reputation: 1978
No-one else will be looking at my scripts either so I don't use many comments. I do use them from time to time though because I know an older version of me will be looking at the scripts, a version of me who might not quite remember how some of the more logically obtuse code came about. So I do add some comments to help the future me.
 
1 members found this post helpful.
Old 06-23-2018, 04:50 AM   #3
Turbocapitalist
Senior Member
 
Registered: Apr 2005
Distribution: Linux Mint, Devuan, OpenBSD
Posts: 3,523
Blog Entries: 3

Rep: Reputation: 1564Reputation: 1564Reputation: 1564Reputation: 1564Reputation: 1564Reputation: 1564Reputation: 1564Reputation: 1564Reputation: 1564Reputation: 1564Reputation: 1564
Yes, but I write fewer comments when they are my own scripts and more when I write scripts for others. Usually I try to answer why something is done a particular way or what the overall goal is. I figure months down the road I will have forgotten. When writing scripts for the others, I usually explain more decisions.
 
2 members found this post helpful.
Old 06-23-2018, 04:52 AM   #4
GazL
Senior Member
 
Registered: May 2008
Posts: 4,769
Blog Entries: 14

Rep: Reputation: Disabled
Comment the whys not the whats. You can usually see the whats by reading the code. Whys tend to be less obvious, especially with the passing of time as hydrurga as already pointed out.

Only comment the whats if it adds value. No need to be Captain Obvious.
 
1 members found this post helpful.
Old 06-23-2018, 11:35 AM   #5
keefaz
LQ Guru
 
Registered: Mar 2004
Distribution: Slackware
Posts: 6,230

Rep: Reputation: 713Reputation: 713Reputation: 713Reputation: 713Reputation: 713Reputation: 713Reputation: 713
No comment, if I no longer understand the code, I rewrite the script
 
Old 06-23-2018, 11:51 AM   #6
Myk267
Member
 
Registered: Apr 2012
Location: California
Posts: 394
Blog Entries: 15

Rep: Reputation: Disabled
Quote:
Originally Posted by Walt.D View Post
I personally don't because I'm the only one in my household that uses linux and the only one that uses the scripts. Since I wrote them, I know what each statement does.

How about you?
Yeah, I write comments.

Sometimes they're temporary. I often write out what I want in text, then fill in the program with code. Sometimes my comment looks like a Haskell type signature, because that can be a useful tool. I usually delete these little notes later after they've served their purpose. It's "Comment-Driven Development" to go along with my testing practices.

Sometimes they describe some set of things I'm likely to forget. I can't keep much Bash or sh syntax in my head, so I'll comment it with something a little more descriptive. Writing things out helps me remember things better, so it's a positive practice in either case. I have a script in which I do something that's sort of "bad" shell practice, and the linter I like picks it out right away, so I've got it commented why I did that particular part so I don't later fix and/or break my own program.

And sometimes they record the frustrations of the moment.
 
Old 06-23-2018, 12:04 PM   #7
dugan
LQ Guru
 
Registered: Nov 2003
Location: Canada
Distribution: Slackware
Posts: 8,493

Rep: Reputation: 3522Reputation: 3522Reputation: 3522Reputation: 3522Reputation: 3522Reputation: 3522Reputation: 3522Reputation: 3522Reputation: 3522Reputation: 3522Reputation: 3522
Considering how hard-to-read BASH string manipulation and regular expressions are? Absolutely.
 
1 members found this post helpful.
Old 06-23-2018, 12:39 PM   #8
scasey
Senior Member
 
Registered: Feb 2013
Location: Tucson, AZ, USA
Distribution: CentOS 7.5
Posts: 1,976

Rep: Reputation: 618Reputation: 618Reputation: 618Reputation: 618Reputation: 618Reputation: 618
Almost always. At a minimum, I'll add a "header" with create date -- or update date-- and a one-liner describing the function or change.

I once worked in a shop that required a comment on every line of code (this wasn't bash,tho):
Code:
actual code                  #description of what the code did
Something broke, and the junior programmer couldn't figure out what was wrong. When I got back from vacation, we discovered that he'd been reviewing the comments, not the code, so he couldn't see the bug in the code...the comment was correct.
 
Old 06-23-2018, 12:57 PM   #9
DavidMcCann
LQ Veteran
 
Registered: Jul 2006
Location: London
Distribution: CentOS, Xubuntu
Posts: 5,108

Rep: Reputation: 1704Reputation: 1704Reputation: 1704Reputation: 1704Reputation: 1704Reputation: 1704Reputation: 1704Reputation: 1704Reputation: 1704Reputation: 1704Reputation: 1704
Quote:
Originally Posted by dugan View Post
Considering how hard-to-read BASH string manipulation and regular expressions are? Absolutely.
Oh, yes!

The other day I found a bug in a program (not bash) I'd written about 30 years ago: thousands of lines and not one comment.
Faced with things in the offending procedure like
Code:
d_t = dir_date + (53 * dir_date + 4) / 3.15576E9  - 1 / 36525
I was left muttering "53? What the %#@&?" I fixed it eventually, but I really wish I'd had a time machine that day!
 
1 members found this post helpful.
Old 06-23-2018, 01:08 PM   #10
danielbmartin
Senior Member
 
Registered: Apr 2010
Location: Apex, NC, USA
Distribution: Mint 17.3
Posts: 1,694

Rep: Reputation: 561Reputation: 561Reputation: 561Reputation: 561Reputation: 561Reputation: 561
If it's worth writing, it's worth commenting.

Daniel B. Martin

.
 
1 members found this post helpful.
Old 06-23-2018, 03:56 PM   #11
jlinkels
LQ Guru
 
Registered: Oct 2003
Location: Bonaire, Leeuwarden
Distribution: Debian /Jessie/Stretch/Sid, Linux Mint DE
Posts: 5,186

Rep: Reputation: 1037Reputation: 1037Reputation: 1037Reputation: 1037Reputation: 1037Reputation: 1037Reputation: 1037Reputation: 1037
Like Myk267 I write in the comments what I want to achieve, why and how and then I code. If I have to think 20 minutes about how to write something less obvious, I am sure I have to spend that 20 minutes again one or two years later and try to understand what I did.

Disposing of code and re-writing it is just plain stupid. It means that the first time you spend thinking about it, and the debugging time is lost. And you have to spend again that time thinking and debugging.

This is, of course, not true if you inherit some non-documented bash scripts. You could better rewrite because there is always the risk you misunderstand non-documented code.

And the power of bash code obfuscation approaches that of C.

jlinkels
 
Old 06-23-2018, 04:18 PM   #12
keefaz
LQ Guru
 
Registered: Mar 2004
Distribution: Slackware
Posts: 6,230

Rep: Reputation: 713Reputation: 713Reputation: 713Reputation: 713Reputation: 713Reputation: 713Reputation: 713
20 minutes to write bash code?
At this point, I'd switch to another language, there is no need to spend lifetime to write scripts imho.
Bash is cool but if script uses too much workarounds to acheive something, I am sure there is another language better suited for the task
 
Old 06-23-2018, 06:27 PM   #13
ondoho
LQ Addict
 
Registered: Dec 2013
Posts: 9,903
Blog Entries: 7

Rep: Reputation: 2438Reputation: 2438Reputation: 2438Reputation: 2438Reputation: 2438Reputation: 2438Reputation: 2438Reputation: 2438Reputation: 2438Reputation: 2438Reputation: 2438
i comment.
http://www.catb.org/esr/writings/uni...s/prodigy.html
 
3 members found this post helpful.
Old 06-29-2018, 06:50 AM   #14
jsbjsb001
Senior Member
 
Registered: Mar 2009
Location: Earth? I would say I hope so but I'm not so sure about that... I could just be a figment of your imagination too.
Distribution: CentOS at the time of this writing, but some others over the years too...
Posts: 2,018

Rep: Reputation: 913Reputation: 913Reputation: 913Reputation: 913Reputation: 913Reputation: 913Reputation: 913Reputation: 913
While I understand what "if statements", etc do and are for; I'm for all intensive purposes quite a n00bie when it comes to coding (be that bash scripts, C, what-ever), and given I've very recently started trying to learn C, then yes, comments at this point really help. Otherwise unless it's just a simple list of commands, I'm likely to forgot what each line actually does exactly.

So yeah, the more code, the more I need to comment about it.
 
Old 06-29-2018, 01:38 PM   #15
rtmistler
Moderator
 
Registered: Mar 2011
Location: MA, USA
Distribution: MINT Debian, Angstrom, SUSE, Ubuntu, Debian
Posts: 7,214
Blog Entries: 12

Rep: Reputation: 2656Reputation: 2656Reputation: 2656Reputation: 2656Reputation: 2656Reputation: 2656Reputation: 2656Reputation: 2656Reputation: 2656Reputation: 2656Reputation: 2656
Quote:
Originally Posted by Walt.D View Post
I personally don't because I'm the only one in my household that uses linux and the only one that uses the scripts. Since I wrote them, I know what each statement does.

How about you?
Yes, I do. Not in every case. If a script truly is simple, and likely also a one-shot, I probably won't. But something I intend to keep around? Absolutely.


Probably because you're the only Linux user, is a better reason to comment them, and especially if they get more complex. But ... it's your choice.
 
  


Reply


Thread Tools Search this Thread
Search this Thread:

Advanced Search

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is Off
HTML code is Off



Similar Threads
Thread Thread Starter Forum Replies Last Post
Where to put startup scripts? susja Linux - Newbie 8 02-05-2012 05:40 AM
Best directory to put my own scripts in...?? WhisperiN Linux - Software 19 11-08-2009 08:50 AM
Where do you generally put custom shell scripts (security-wise)? BILMO Linux - Security 3 01-18-2007 02:23 AM
Where to put mldonkey scripts? Aioth Slackware 2 06-19-2004 09:29 AM
put my scripts to PATH Boby Linux - Newbie 1 06-14-2004 01:01 PM

LinuxQuestions.org > Forums > Non-*NIX Forums > Programming

All times are GMT -5. The time now is 01:00 PM.

Main Menu
Advertisement
My LQ
Write for LQ
LinuxQuestions.org is looking for people interested in writing Editorials, Articles, Reviews, and more. If you'd like to contribute content, let us know.
Main Menu
Syndicate
RSS1  Latest Threads
RSS1  LQ News
Twitter: @linuxquestions
Facebook: linuxquestions Google+: linuxquestions
Open Source Consulting | Domain Registration