* [TUHS] daemons are not to be exorcised @ 2018-03-21 14:17 Noel Chiappa 2018-03-21 15:03 ` Clem Cole 0 siblings, 1 reply; 41+ messages in thread From: Noel Chiappa @ 2018-03-21 14:17 UTC (permalink / raw) > From: Larry McVoy <lm at mcvoy.com> > Going forward, I wish that people tried to be simple as they tackle the > more complicated problems we have. I have a couple of relevant quotations on my 'Some Computer-Related Lines' page: "Deliberate complexity is the mark of an amateur. Elegant simplicity is the mark of a master." -- Unknown, quoted by Robert A. Crawford "Fools ignore complexity. Pragmatists suffer it. Some can avoid it. Geniuses remove it." -- Alan Perlis "The most reliable components are the ones you leave out." -- Gordon Bell (For software, the latter needs to be read as 'The most bug-free lines of codqe are the ones you leave out', of course.) I remember watching the people building the LISP machine, and thinking 'Wow, that system is complex'. I eventually decided the problem was that they were _too_ smart. They could understand, and retain in their minds, all that complexity. Noel ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 14:17 [TUHS] daemons are not to be exorcised Noel Chiappa @ 2018-03-21 15:03 ` Clem Cole 2018-03-21 16:18 ` Arthur Krewat 0 siblings, 1 reply; 41+ messages in thread From: Clem Cole @ 2018-03-21 15:03 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 2782 bytes --] On Wed, Mar 21, 2018 at 10:17 AM, Noel Chiappa <jnc at mercury.lcs.mit.edu> wrote: > > From: Larry McVoy <lm at mcvoy.com> > > > Going forward, I wish that people tried to be simple as they tackle > the > > more complicated problems we have. > > I have a couple of relevant quotations on my 'Some Computer-Related Lines' > page: > > "Deliberate complexity is the mark of an amateur. Elegant simplicity is > the > mark of a master." > -- Unknown, quoted by Robert A. Crawford > > "Fools ignore complexity. Pragmatists suffer it. Some can avoid it. > Geniuses > remove it." > -- Alan Perlis > > "The most reliable components are the ones you leave out." > -- Gordon Bell > > (For software, the latter needs to be read as 'The most bug-free lines of > code are the ones you leave out', of course.) > Amen... > > > I remember watching the people building the LISP machine, and thinking > 'Wow, > that system is complex'. I eventually decided the problem was that they > were > _too_ smart. They could understand, and retain in their minds, all that > > complexity. And therein lies another interesting paradox... smart people don't always realize that their being "smarter than the average bear" as it were, means mortals are unlikely to be able to understand what you are doing. Or more importantly, your might not be that 'smart' later. I'll never forget a conversation with one of my officemates at Masscomp who had come from Steve Ward's group at MIT, who I will not name. But he is one the smartest people I ever worked with and someone I have tremendous respect. CMU used to have a required SW Engineering course and one of the things drilled into us was commenting (you can usually tell code I worked on by the dyslexia in my comments - but I do try to leave bit crumbs). Anyway, said person never had a such a course. He says to me -- "Well I only comment things I did not understand." I looked at him in awe and said: "'Fred' - you are one of the smartest people I know, please put the comments in there for the rest of us." A bit later, he got cut by his own sword. He had had to pick up a piece of code he had written a long time before and of course the context that he had had when he wrote it was by that time completely lost. Guess what - he could not understand what the code was doing [BTW: The last time I saw something he wrote, he was wonderful at writing comments]. To me, "keep it short, simple, but always explain your intentions in prose" need to be the guiding lights for programmers. Clem ᐧ ᐧ -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/abc132e1/attachment.html> ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 15:03 ` Clem Cole @ 2018-03-21 16:18 ` Arthur Krewat 2018-03-21 17:28 ` Paul Winalski 0 siblings, 1 reply; 41+ messages in thread From: Arthur Krewat @ 2018-03-21 16:18 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 1794 bytes --] On 3/21/2018 11:03 AM, Clem Cole wrote: > > To me, "keep it short, simple, but always explain your intentions in > prose" need to be the guiding lights for programmers. It was instilled in me early on by my one and only mentor that someone that comes along later may have no idea what my code is doing. So comment. Even when it might be self-explanitory, comment anyway. This was on TOPS-10 back in the early 80's, usually MACRO-10 although I dabbled in ALGOL, SNOBOL, FORTRAN, etc. When I look back at my own code, I can read the comments as the plot-line, so to speak, and the code itself just follows along. I have noticed a lot of newer programmers these days that say (paraphrased): "Good code will explain itself" as a reason not to comment. Mostly C++ and Java programmers. I call bullshit on that. Not commenting is lazy. There's no reason NOT to comment. Most of my stuff has more comments byte-wise than real code. Something I wrote just yesterday as part of a much larger project: // remove the UTF-8 BOM at the beginning of a line of text. char bom[] = { 0xEF, 0xBB, 0xBF, 0 }; // UTF-8 BOM void remove_bom(char *str) { if (strncmp(str, bom, strlen(bom)) == 0) { // can we find the BOM at the beginning of the line? strcpy(str, str + strlen(bom)); // yup, kill it. } } While that is definitely self-explanitory, I just can't help myself - and no, don't comment on my brazen assumptions of string length, or the fact that I assume it's UTF-8 - I've taken care of all of that elsewhere... ;) ak -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/d7cca4d3/attachment.html> ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 16:18 ` Arthur Krewat @ 2018-03-21 17:28 ` Paul Winalski 2018-03-21 17:33 ` George Michaelson ` (4 more replies) 0 siblings, 5 replies; 41+ messages in thread From: Paul Winalski @ 2018-03-21 17:28 UTC (permalink / raw) On 3/21/18, Arthur Krewat <krewat at kilonet.net> wrote: > > It was instilled in me early on by my one and only mentor that someone > that comes along later may have no idea what my code is doing. So > comment. Even when it might be self-explanitory, comment anyway. In my 40-year career as a programmer, I've more than once had that someone who comes along later be myself. I also apply what I call the Bus Principle. If you get hit by a bus and killed, one of your colleagues is going to have to take over your work. Give them a fighting chance with code comments, and maybe even a design document for large or complex things. > I have noticed a lot of newer programmers these days that say > (paraphrased): "Good code will explain itself" as a reason not to > comment. Mostly C++ and Java programmers. > > I call bullshit on that. Not commenting is lazy. There's no reason NOT > to comment. Amen to that! Good comments are one of the things that distinguishes Software Engineering from mere programming. -Paul W. ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 17:28 ` Paul Winalski @ 2018-03-21 17:33 ` George Michaelson 2018-03-21 17:50 ` Arthur Krewat 2018-03-21 19:37 ` Paul Winalski 2018-03-21 17:34 ` Larry McVoy ` (3 subsequent siblings) 4 siblings, 2 replies; 41+ messages in thread From: George Michaelson @ 2018-03-21 17:33 UTC (permalink / raw) I think there's a middle ground. saying "this is a loop" is not informative. saying "I did this as a loop because..." can be very informative. I think with short circuit evaluation and side-effects in C, this kind of code is especially worth commenting: people need to remember the right hand side of a complex set of expressions might actually not have done anything. Here at IETF a really cute corner-case of optimization-for-bug came up. Somebody who thought they had worked out a given packet in UDP dns messages always had a pair of specific chars 0x0c and 0xc0 in sequence (or something) and coded for it, not realizing they were coding below the outcome of a DNS label compression pattern which didn't always hold. Sometimes, people code from faulty or incomplete information. So this one, (for instance) would have been much better commented than not. It would have let the following people hit the coder with a thin whippy stick. On Wed, Mar 21, 2018 at 5:28 PM, Paul Winalski <paul.winalski at gmail.com> wrote: > On 3/21/18, Arthur Krewat <krewat at kilonet.net> wrote: >> >> It was instilled in me early on by my one and only mentor that someone >> that comes along later may have no idea what my code is doing. So >> comment. Even when it might be self-explanitory, comment anyway. > > In my 40-year career as a programmer, I've more than once had that > someone who comes along later be myself. > > I also apply what I call the Bus Principle. If you get hit by a bus > and killed, one of your colleagues is going to have to take over your > work. Give them a fighting chance with code comments, and maybe even > a design document for large or complex things. > >> I have noticed a lot of newer programmers these days that say >> (paraphrased): "Good code will explain itself" as a reason not to >> comment. Mostly C++ and Java programmers. >> >> I call bullshit on that. Not commenting is lazy. There's no reason NOT >> to comment. > > Amen to that! Good comments are one of the things that distinguishes > Software Engineering from mere programming. > > -Paul W. ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 17:33 ` George Michaelson @ 2018-03-21 17:50 ` Arthur Krewat 2018-03-21 19:49 ` A. P. Garcia 2018-03-21 19:37 ` Paul Winalski 1 sibling, 1 reply; 41+ messages in thread From: Arthur Krewat @ 2018-03-21 17:50 UTC (permalink / raw) On 3/21/2018 1:33 PM, George Michaelson wrote: > I think there's a middle ground. saying "this is a loop" is not > informative. saying "I did this as a loop because..." can be very > informative. Absolutely. Using my "comments as the plot" analogy, that would be like the main character in a movie saying "this is a chair" instead of "this is my dad's chair". So much more meaning ;) And bringing it back to UNIX, I remember reading here on this list that comments were sanitized, removing any humor. Anyone got any good examples of that? ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 17:50 ` Arthur Krewat @ 2018-03-21 19:49 ` A. P. Garcia 0 siblings, 0 replies; 41+ messages in thread From: A. P. Garcia @ 2018-03-21 19:49 UTC (permalink / raw) On Mar 21, 2018 12:51 PM, "Arthur Krewat" <krewat at kilonet.net> wrote: On 3/21/2018 1:33 PM, George Michaelson wrote: > I think there's a middle ground. saying "this is a loop" is not > informative. saying "I did this as a loop because..." can be very > informative. > Absolutely. Using my "comments as the plot" analogy, that would be like the main character in a movie saying "this is a chair" instead of "this is my dad's chair". So much more meaning ;) And bringing it back to UNIX, I remember reading here on this list that comments were sanitized, removing any humor. Anyone got any good examples of that? Well, I remember many years ago seeing a comment in the Linux kernel to the effect that the kernel would never be larger than 2 MB IIRC. Which to me is kind of humorous in retrospect. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/2a9bcb35/attachment-0001.html> ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 17:33 ` George Michaelson 2018-03-21 17:50 ` Arthur Krewat @ 2018-03-21 19:37 ` Paul Winalski 1 sibling, 0 replies; 41+ messages in thread From: Paul Winalski @ 2018-03-21 19:37 UTC (permalink / raw) On 3/21/18, George Michaelson <ggm at algebras.org> wrote: > > I think with short circuit evaluation and side-effects in C, this kind > of code is especially worth commenting: people need to remember the > right hand side of a complex set of expressions might actually not > have done anything. > One thing that is always worth a comment is Perl regular expressions. A prose description of what the regex is supposed to match can save someone else a lot of time. -Paul W. ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 17:28 ` Paul Winalski 2018-03-21 17:33 ` George Michaelson @ 2018-03-21 17:34 ` Larry McVoy 2018-03-22 2:24 ` Dave Horsfall 2018-03-21 17:39 ` WIlliam Cheswick ` (2 subsequent siblings) 4 siblings, 1 reply; 41+ messages in thread From: Larry McVoy @ 2018-03-21 17:34 UTC (permalink / raw) On Wed, Mar 21, 2018 at 01:28:34PM -0400, Paul Winalski wrote: > On 3/21/18, Arthur Krewat <krewat at kilonet.net> wrote: > > > > It was instilled in me early on by my one and only mentor that someone > > that comes along later may have no idea what my code is doing. So > > comment. Even when it might be self-explanitory, comment anyway. > > In my 40-year career as a programmer, I've more than once had that > someone who comes along later be myself. Yep. Someone once told me "any code that you wrote more than 6 months ago might as well have been written by someone else. So write it in a way that you can debug it". ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 17:34 ` Larry McVoy @ 2018-03-22 2:24 ` Dave Horsfall 0 siblings, 0 replies; 41+ messages in thread From: Dave Horsfall @ 2018-03-22 2:24 UTC (permalink / raw) On Wed, 21 Mar 2018, Larry McVoy wrote: > Yep. Someone once told me "any code that you wrote more than 6 months > ago might as well have been written by someone else. So write it in a > way that you can debug it". Yep, and I'm glad that I had bosses to whom I didn't have to explain why my comments were so voluminous. And who first said "Write your code as though the next person to maintain it is a psychotic axe-wielding murderer who knows where you live"? I've often thought that way (as the murderer I mean, not the murderee). I'd name names, but he might be on this list... -- Dave Horsfall DTM (VK2KFU) "Those who don't understand security will suffer." ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 17:28 ` Paul Winalski 2018-03-21 17:33 ` George Michaelson 2018-03-21 17:34 ` Larry McVoy @ 2018-03-21 17:39 ` WIlliam Cheswick 2018-03-21 17:52 ` Arthur Krewat 2018-03-21 17:56 ` Nemo 2018-03-21 18:04 ` Dan Cross 4 siblings, 1 reply; 41+ messages in thread From: WIlliam Cheswick @ 2018-03-21 17:39 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 449 bytes --] > On Mar 21, 2018, at 1:28 PM, Paul Winalski <paul.winalski at gmail.com> wrote: > > In my 40-year career as a programmer, I've more than once had that > someone who comes along later be myself. “Comments are love letters we write to our future selves.” - Jon Bentley -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/760a9e6e/attachment-0001.html> ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 17:39 ` WIlliam Cheswick @ 2018-03-21 17:52 ` Arthur Krewat 0 siblings, 0 replies; 41+ messages in thread From: Arthur Krewat @ 2018-03-21 17:52 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 345 bytes --] On 3/21/2018 1:39 PM, WIlliam Cheswick wrote: > > “Comments are love letters we write to our future selves.” > - Jon Bentley Truth be told, I sometimes get into a melancholy state, and go back to code I wrote decades ago just to go through the history section and remind myself why I got into this line of work in the first place. ak ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 17:28 ` Paul Winalski ` (2 preceding siblings ...) 2018-03-21 17:39 ` WIlliam Cheswick @ 2018-03-21 17:56 ` Nemo 2018-03-21 18:01 ` Larry McVoy 2018-03-21 18:04 ` Dan Cross 4 siblings, 1 reply; 41+ messages in thread From: Nemo @ 2018-03-21 17:56 UTC (permalink / raw) On 21 March 2018 at 13:28, Paul Winalski <paul.winalski at gmail.com> wrote (in part): > I also apply what I call the Bus Principle. If you get hit by a bus > and killed, one of your colleagues is going to have to take over your > work. Give them a fighting chance with code comments, and maybe even > a design document for large or complex things. A manager insisted that everyone spend the last 15min of the day writing down what was done that day on a sheet of paper and putting in your desk drawer. No one was run over by a bus but the paper became the first thing many consulted next day (and the act of writing consolidated thoughts -- something much lost today). N. ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 17:56 ` Nemo @ 2018-03-21 18:01 ` Larry McVoy 0 siblings, 0 replies; 41+ messages in thread From: Larry McVoy @ 2018-03-21 18:01 UTC (permalink / raw) On Wed, Mar 21, 2018 at 01:56:38PM -0400, Nemo wrote: > On 21 March 2018 at 13:28, Paul Winalski <paul.winalski at gmail.com> > wrote (in part): > > I also apply what I call the Bus Principle. If you get hit by a bus > > and killed, one of your colleagues is going to have to take over your > > work. Give them a fighting chance with code comments, and maybe even > > a design document for large or complex things. > > A manager insisted that everyone spend the last 15min of the day > writing down what was done that day on a sheet of paper and putting in > your desk drawer. No one was run over by a bus but the paper became > the first thing many consulted next day (and the act of writing > consolidated thoughts -- something much lost today). I'd like a $repo/src/STATE file filled out at the end of my day. Back in the day I had a coworker that would do a find /home/bk/lm -maxdepth 3 -name STATE -mtime -1 in the morning to see what I had been up to :) The act of dumping what I was trying to do, what I had figured out so far, just dumping state, frequently lead to the solution. So it had the "bad" effect of making me work longer to actually finish. I've worked on problems in the kernel that were hard enough that it could take me as much as 8 hours of thinking to get back to where I was yesterday. The STATE file came out of that, it ramped me up faster. --lm ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 17:28 ` Paul Winalski ` (3 preceding siblings ...) 2018-03-21 17:56 ` Nemo @ 2018-03-21 18:04 ` Dan Cross 2018-03-21 19:56 ` Clem Cole 4 siblings, 1 reply; 41+ messages in thread From: Dan Cross @ 2018-03-21 18:04 UTC (permalink / raw) On Wed, Mar 21, 2018 at 1:28 PM, Paul Winalski <paul.winalski at gmail.com> wrote: > On 3/21/18, Arthur Krewat <krewat at kilonet.net> wrote: > > [...] > > I call bullshit on that. Not commenting is lazy. There's no reason NOT > > to comment. > > Amen to that! Good comments are one of the things that distinguishes > Software Engineering from mere programming. Critical to that, however, is the adjective "good", as in "good comments." Writing comments can be incredibly useful, but writing *good* comments is a learned skill that requires judgement and taste. Much ado is made nowadays about the "craft" of programming. I dislike this analogy for a number of reasons, but there's no denying that good programming has a craft element to it, and I claim that good commenting is one of the harder of the craft skills to master. In particular, there *are* good reasons NOT to comment something: the code is so obvious the comment would just be a restatement of the manifestly evident, but with the added visual clutter and cognitive load imposed by simply existing and the added maintenance burden of being kept in sync. When I see a comment, I often take it as an indication that something notable is happening: if the comment is superfluous then I'm left wondering WHY it's there and what about the code I'm missing. Similarly, comments must be maintained: my experience is that out-of-date comments that have fallen out of sync with the code are strictly a liability. Finding balance between the costs of commenting and the positive benefits of comments takes time to develop. When I was younger, I dressed somewhat better than I do now and when I was in the Marines I once found myself in a social situation where it made sense to wear a tweed jacket. Another Marine introduced me to the concept of, "always, sometimes, never" vis which of the three buttons on the front of my jacket to button: top button always, middle button sometimes, bottom button never (whether this is good fashion advice or not is another matter). I think that something analogous is true of writing good comments: 1. A comment should never simply parrot the code: i++; // Increment i. 2. A comment should sometimes explain *what* the code is doing. 3. A comment should always explain *why* the code is doing what it's doing. Note that these are specific to comments, not to code: it does not follow, for example, that a line or stanza of code should always be adorned with a comment explaining why it exists: (think, `i++; // Increment the array index for the next iteration of the loop.` Ugh). Btw, this is something I think that Unix did very well. - Dan C. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/29852f97/attachment.html> ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 18:04 ` Dan Cross @ 2018-03-21 19:56 ` Clem Cole 2018-03-21 20:04 ` [TUHS] comments ( was daemons exorcised ) Earl Baugh 2018-03-21 20:13 ` [TUHS] daemons are not to be exorcised Paul Winalski 0 siblings, 2 replies; 41+ messages in thread From: Clem Cole @ 2018-03-21 19:56 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 1039 bytes --] On Wed, Mar 21, 2018 at 2:04 PM, Dan Cross <crossd at gmail.com> wrote: > > Critical to that, however, is the adjective "good", as in "good comments." > Writing comments can be incredibly useful, but writing *good* comments is a > learned skill that requires judgement and taste. > > .... > > 1. A comment should never simply parrot the code: i++; // Increment i. > 2. A comment should sometimes explain *what* the code is doing. > 3. A comment should always explain *why* the code is doing what it's doing. > i.e. there is a difference between: i++; // Increment i *v.s.* the line: ptr->field++; // ensure reference count stays sane The former fails your first test, the second follows 2 & 3 as a note to my future self that this is where I am doing the this piece of support work (reference count maintenance). Clem ᐧ -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/6803fa6c/attachment.html> ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] comments ( was daemons exorcised ) 2018-03-21 19:56 ` Clem Cole @ 2018-03-21 20:04 ` Earl Baugh 2018-03-21 20:18 ` Paul Winalski 2018-03-21 20:13 ` [TUHS] daemons are not to be exorcised Paul Winalski 1 sibling, 1 reply; 41+ messages in thread From: Earl Baugh @ 2018-03-21 20:04 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 492 bytes --] I remember seeing a fortune or the like that said : Documentation is like sex. When it’s good its very very good. When it’s bad, it’s better than nothing. I found many times this rule applies to comments I’ve encountered in difficult code I’ve had the chore in debugging. :-) Earl Sent from my iPhone > ᐧ -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/fb6d6e79/attachment.html> ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] comments ( was daemons exorcised ) 2018-03-21 20:04 ` [TUHS] comments ( was daemons exorcised ) Earl Baugh @ 2018-03-21 20:18 ` Paul Winalski 2018-03-21 20:51 ` Ron Natalie 0 siblings, 1 reply; 41+ messages in thread From: Paul Winalski @ 2018-03-21 20:18 UTC (permalink / raw) A co-worker of mine once had a particularly nasty time debugging a customer bug. When he finally tracked down the faulty code, it was preceded by a comment that said, "Someday someone will hate me for this." -Paul W. ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] comments ( was daemons exorcised ) 2018-03-21 20:18 ` Paul Winalski @ 2018-03-21 20:51 ` Ron Natalie 0 siblings, 0 replies; 41+ messages in thread From: Ron Natalie @ 2018-03-21 20:51 UTC (permalink / raw) Having been a supervisor of a large software package of which there were programmers of all skill levels I would periodically review the software. Every once and a while I would note something that needed to be fixed by putting the comment "BOGUS" on that region. Depending on out bad it was, the number of Os in BOGUS would increase. My second-in-command realized this one section needed to be rewritten when it was marked BOOOOOOOOOOOOGUS. ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] daemons are not to be exorcised 2018-03-21 19:56 ` Clem Cole 2018-03-21 20:04 ` [TUHS] comments ( was daemons exorcised ) Earl Baugh @ 2018-03-21 20:13 ` Paul Winalski 2018-03-21 20:28 ` [TUHS] Comments in early Unix systems Warren Toomey 1 sibling, 1 reply; 41+ messages in thread From: Paul Winalski @ 2018-03-21 20:13 UTC (permalink / raw) Regarding comments, when I'm modifying code to fix a bug I find it useful to insert a comment that references the bug's number in the bug tracking system. It can help answer the question "why is this code here?" for someone reading the code later on, and sometimes it can prevent regressions being introduced. To bring this back to Unix, how well have the various commenting principles we've been discussing been adhered to in the code base? -Paul W. ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-21 20:13 ` [TUHS] daemons are not to be exorcised Paul Winalski @ 2018-03-21 20:28 ` Warren Toomey 2018-03-21 20:48 ` Ron Natalie ` (3 more replies) 0 siblings, 4 replies; 41+ messages in thread From: Warren Toomey @ 2018-03-21 20:28 UTC (permalink / raw) On Wed, Mar 21, 2018 at 04:13:42PM -0400, Paul Winalski wrote: >To bring this back to Unix, how well have the various commenting >principles we've been discussing been adhered to in the code base? This is something that has bugged me forever. The Unix design is simple and elegant. The manuals are lucid and understandable. However, there is next to no commenting in the early code bases. Why? [and I know ken is reading this] Given that the comments never made it into the compiled code, there was no space reason to omit comments. There must have been another reason. Cheers, Warren ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-21 20:28 ` [TUHS] Comments in early Unix systems Warren Toomey @ 2018-03-21 20:48 ` Ron Natalie 2018-03-21 22:18 ` William Corcoran ` (2 subsequent siblings) 3 siblings, 0 replies; 41+ messages in thread From: Ron Natalie @ 2018-03-21 20:48 UTC (permalink / raw) > Given that the comments never made it into the compiled code, there was no space reason to omit comments. There must have been another reason. Attitudes in software engineering have changed a lot over the 60 years we've been programming. Actually, UNIX was better than a lot of OS sources I've dealt with. Further, you had disk space and compile time issues to worry about. Amusingly, I worked with Mike Muuss for years (first at JHU and then at BRL). Mike believed much in putting comments on everything. The DMR "You're not expected to understand this" comment incensed him so much (yes I know that's not what DMR meant) that he wrote an entire page to explain just what retu/aretu/setka6 were doing there. Amusingly, Mike was further incensed when Mike submitted a bunch of revisions to BSD and McKusick, in the name of maintaining a uniform commenting style, deleted all the comments. I guess NONE is pretty consistent. While this next anecdote strays from UNIX, I worked on a project my first job out of college on a database system written in Fortran and Macro 11 on a two-system RSX-11M+ system. One of the early projects there was to write a program that counted "lines of code" to report to the customer progress or something. The head of software came up to the head database programmer (not me) and said, "Do you know that we ran our line counter on your modules and it said that there is only one line of comments in your entire module). Jerry pointed out their software had to be in error, there weren't any lines of comments. In fact, a closer examination noted it counted one of the MACRO-11 directives (.TITLE or something like that) as a comment. In Jerry's defense, there were comments in the code, just not lines that were only comments. They were just put at the end of the lines of existing instructions. ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-21 20:28 ` [TUHS] Comments in early Unix systems Warren Toomey 2018-03-21 20:48 ` Ron Natalie @ 2018-03-21 22:18 ` William Corcoran 2018-03-21 23:02 ` Clem Cole 2018-03-21 23:17 ` Arthur Krewat 2018-03-21 23:45 ` Warner Losh 2018-03-22 0:58 ` Andy Kosela 3 siblings, 2 replies; 41+ messages in thread From: William Corcoran @ 2018-03-21 22:18 UTC (permalink / raw) Along the same lines: As UNIX *transitioned from the relative safety of academia (V7) into the cold, cruel corporate world (System V), was there a corresponding effort to maintain and protect the UNIX codebase into a unified master repository with SCCS, for example? Is there any chance of finding a publicly available UNIX archive that includes the corresponding SCCS data for UNIX---to the extent that SCCS deltas and PRS comments can be examined? Bill Corcoran (*) IMHO On Mar 21, 2018, at 4:28 PM, Warren Toomey <wkt at tuhs.org> wrote: . . . Given that the comments never made it into the compiled code, there was no space reason to omit comments. There must have been another reason. Cheers, Warren ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-21 22:18 ` William Corcoran @ 2018-03-21 23:02 ` Clem Cole 2018-03-22 1:31 ` Larry McVoy 2018-03-21 23:17 ` Arthur Krewat 1 sibling, 1 reply; 41+ messages in thread From: Clem Cole @ 2018-03-21 23:02 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 698 bytes --] On Wed, Mar 21, 2018 at 6:18 PM, William Corcoran <wlc at jctaylor.com> wrote: > Along the same lines: > ... > > Is there any chance of finding a publicly available UNIX archive that > includes the corresponding SCCS data for UNIX---to the extent that SCCS > deltas and PRS comments can be examined? > > Bill check out Diomidis Spinellis truely amazing work at: https://github.com/dspinellis/unix-history-repo He has done an amazing job of reconstructing much of the lost work. It is a treasure for us all. Clem ᐧ -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/5c507626/attachment.html> ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-21 23:02 ` Clem Cole @ 2018-03-22 1:31 ` Larry McVoy 0 siblings, 0 replies; 41+ messages in thread From: Larry McVoy @ 2018-03-22 1:31 UTC (permalink / raw) On Wed, Mar 21, 2018 at 07:02:24PM -0400, Clem Cole wrote: > On Wed, Mar 21, 2018 at 6:18 PM, William Corcoran <wlc at jctaylor.com> wrote: > > > Along the same lines: > > ???... > > > > Is there any chance of finding a publicly available UNIX archive that > > includes the corresponding SCCS data for UNIX---to the extent that SCCS > > deltas and PRS comments can be examined? > > > > > Bill check out Diomidis Spinellis truely amazing work at: > https://github.com/dspinellis/unix-history-repo > > ???He has done an amazing job of reconstructing much of the lost work. It is > a treasure for us all. Agreed but I'd still like the SCCS history. I have it somewhere for BSD, it was on Kirk's cds but I'd love to wander through the SCCS from Bell Labs. I'm an SCCS fan, BitKeeper (sadly forgotten these days, my baby) was SCCS on steriods. BK has an import tool that will take SCCS history and intuit what we today call commits, it will find the changes that are in the same time and by the same person and create a changeset for that. BK is still, to this day, by far the best tool to use to browse history. So if I could get the SCCS history for early Unix I could give you all a super pleasant way to look at that history (we open sourced BK when we shut down). --lm ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-21 22:18 ` William Corcoran 2018-03-21 23:02 ` Clem Cole @ 2018-03-21 23:17 ` Arthur Krewat 2018-03-21 23:50 ` Larry McVoy 1 sibling, 1 reply; 41+ messages in thread From: Arthur Krewat @ 2018-03-21 23:17 UTC (permalink / raw) On 3/21/2018 6:18 PM, William Corcoran wrote: > Given that the comments never made it into the compiled code, there > was no space reason to omit comments. There must have been another > reason. I used to regularly compress sources of various distributions (not UNIX, but inn, pine, elm, etc) that I compiled, just to save space. And that was in the early 90's when I could buy a 1GB SCSI drive for $1000. I can't imagine working off of the early hard drives... ak ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-21 23:17 ` Arthur Krewat @ 2018-03-21 23:50 ` Larry McVoy 2018-03-22 0:55 ` Mike Markowski 0 siblings, 1 reply; 41+ messages in thread From: Larry McVoy @ 2018-03-21 23:50 UTC (permalink / raw) On Wed, Mar 21, 2018 at 07:17:11PM -0400, Arthur Krewat wrote: > I used to regularly compress sources of various distributions (not UNIX, but > inn, pine, elm, etc) that I compiled, just to save space. > > And that was in the early 90's when I could buy a 1GB SCSI drive for $1000. > I can't imagine working off of the early hard drives... I was sys admin for a Masscomp with a 40MB disk and 20 users. That was, um, "fun". ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-21 23:50 ` Larry McVoy @ 2018-03-22 0:55 ` Mike Markowski 2018-03-22 1:00 ` Larry McVoy 0 siblings, 1 reply; 41+ messages in thread From: Mike Markowski @ 2018-03-22 0:55 UTC (permalink / raw) On 03/21/2018 07:50 PM, Larry McVoy wrote: > On Wed, Mar 21, 2018 at 07:17:11PM -0400, Arthur Krewat wrote: >> I used to regularly compress sources of various distributions (not UNIX, but >> inn, pine, elm, etc) that I compiled, just to save space. >> >> And that was in the early 90's when I could buy a 1GB SCSI drive for $1000. >> I can't imagine working off of the early hard drives... > > I was sys admin for a Masscomp with a 40MB disk and 20 users. That > was, um, "fun". I remember Masscomp... We used one (I forget model) in the field in the late 80s in the back of a tractor trailer. We'd capture radar signals with it because it allowed data acquisition to not be swapped out. It was a very expensive failure if, just as you started getting the short radar return, something like system logging swapped you out for a little! Mike Markowski ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-22 0:55 ` Mike Markowski @ 2018-03-22 1:00 ` Larry McVoy 0 siblings, 0 replies; 41+ messages in thread From: Larry McVoy @ 2018-03-22 1:00 UTC (permalink / raw) On Wed, Mar 21, 2018 at 08:55:44PM -0400, Mike Markowski wrote: > On 03/21/2018 07:50 PM, Larry McVoy wrote: > >On Wed, Mar 21, 2018 at 07:17:11PM -0400, Arthur Krewat wrote: > >>I used to regularly compress sources of various distributions (not UNIX, but > >>inn, pine, elm, etc) that I compiled, just to save space. > >> > >>And that was in the early 90's when I could buy a 1GB SCSI drive for $1000. > >>I can't imagine working off of the early hard drives... > > > >I was sys admin for a Masscomp with a 40MB disk and 20 users. That > >was, um, "fun". > > I remember Masscomp... We used one (I forget model) in the field in the > late 80s in the back of a tractor trailer. We'd capture radar signals with > it because it allowed data acquisition to not be swapped out. It was a very > expensive failure if, just as you started getting the short radar return, > something like system logging swapped you out for a little! I remember the Masscomps we had fondly. The ones we had were 68000 based and they had two of those CPUs running in lock step (or something, Clem will correct this, he was one of the main devs at Masscomp) because the 68K didn't do VM right. I can't remember the details, it was something like they didn't handle faults right so they ran two CPUs and when the fault happened the 2nd CPU somehow got involved. Clem, what model was that? And can you provide the real version of what I was trying say? --lm ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-21 20:28 ` [TUHS] Comments in early Unix systems Warren Toomey 2018-03-21 20:48 ` Ron Natalie 2018-03-21 22:18 ` William Corcoran @ 2018-03-21 23:45 ` Warner Losh 2018-03-22 0:31 ` Steve Johnson 2018-03-22 0:58 ` Andy Kosela 3 siblings, 1 reply; 41+ messages in thread From: Warner Losh @ 2018-03-21 23:45 UTC (permalink / raw) On Wed, Mar 21, 2018 at 2:28 PM, Warren Toomey <wkt at tuhs.org> wrote: > On Wed, Mar 21, 2018 at 04:13:42PM -0400, Paul Winalski wrote: > >> To bring this back to Unix, how well have the various commenting >> principles we've been discussing been adhered to in the code base? >> > > This is something that has bugged me forever. > > The Unix design is simple and elegant. The manuals are lucid and > understandable. However, there is next to no commenting in the > early code bases. Why? [and I know ken is reading this] > > Given that the comments never made it into the compiled code, there > was no space reason to omit comments. There must have been another > reason. > I was told in school (in 1985) that if I was ever lucky enough to have access to the unix source, I'd find there were no comments. The reason, I was told at the time, was that comments would make the source code useful, and selling software was something AT&T couldn't do due to some consent decree. I've never been able to verify this story, but it came from someone who started with v5. Sadly, he passed away 15 years ago, or I'd just ask him again... Warner -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/33017e3a/attachment.html> ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-21 23:45 ` Warner Losh @ 2018-03-22 0:31 ` Steve Johnson 0 siblings, 0 replies; 41+ messages in thread From: Steve Johnson @ 2018-03-22 0:31 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 2921 bytes --] "I was told in school (in 1985) that if I was ever lucky enough to have access to the unix source, I'd find there were no comments. The reason, I was told at the time, was that comments would make the source code useful, and selling software was something AT&T couldn't do due to some consent decree. I've never been able to verify this story, but it came from someone who started with v5. Sadly, he passed away 15 years ago, or I'd just ask him again..." Ah, the consent decree. The basic idea of the consent decree was to prevent AT&T's regulated monopoly from giving it an unfair advantage in other areas. And, since the regulation guaranteed a rate of return, certain restrictions were put on the ability of AT&T to do business outside of the telephone arena. In particular, one requirement was that AT&T MUST patent anything they did that was patentable. And furthermore, they must license that patent to all comers at a "reasonable" rate. The decree was signed in 1956. And then, along came software! AT&T foundi itself required to patent software inventions at a time that nobody was sure what that meant, or whether software was even patentable. There were some very strange patents, or at least patent applications, that came out of this. I remember an algorithm for generating permutations that was recast as a relay computer because that was probably patenable and, if so, AT&T had to do it. Also, the mindset of AT&T was to plan in 20 year timescales, and they had trouble understanding the increasing speed of software innovation. The patent department's attitude about a lot of the issues of Unix licensing, etc., was basically to wait 5 years until there was some precedent before acting. Meanwhile, when they took an interest they would issue some directive, often to reverse themselves several months later. I remember before one of the releases we had to make sure we had a copyright notice on every file, only to be told six months later to make sure that we removed all copyright notices from all files. One run-in that I had with the legal team happened just as Unix and C were beginning to become popular, and some new C compilers were appearing. I made a strong appeal, with the support of my management, to release the front end of PCC (or at least the Yacc grammar for C) into the public domain, to try to encourage some consistency in what we intended to be a portable language. Meetings dragged on for months, and we were finally told no. I don't know whether, had I been successfu, we could have avoided all the ANSI / Posix confusion that came later, or at least limit the number of incompatibilities that rapidly appeared in "C" compilers. But it might have helped... Steve -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/93737de3/attachment.html> ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-21 20:28 ` [TUHS] Comments in early Unix systems Warren Toomey ` (2 preceding siblings ...) 2018-03-21 23:45 ` Warner Losh @ 2018-03-22 0:58 ` Andy Kosela 2018-03-22 1:27 ` Larry McVoy 3 siblings, 1 reply; 41+ messages in thread From: Andy Kosela @ 2018-03-22 0:58 UTC (permalink / raw) On Wednesday, March 21, 2018, Warren Toomey <wkt at tuhs.org> wrote: > On Wed, Mar 21, 2018 at 04:13:42PM -0400, Paul Winalski wrote: > >> To bring this back to Unix, how well have the various commenting >> principles we've been discussing been adhered to in the code base? >> > > This is something that has bugged me forever. > > The Unix design is simple and elegant. The manuals are lucid and > understandable. However, there is next to no commenting in the > early code bases. Why? [and I know ken is reading this] > > Given that the comments never made it into the compiled code, there > was no space reason to omit comments. There must have been another > reason. > > I think some answers could be find in "Practice of Programming" by Rob Pike and Brian Kernighan. In the section about comments they express why they are not big fans of verbose commenting style. They also state: "Comments are meant to help the reader of a program. They do not help by saying things the code already plainly says, or by contradicting the code, or by distracting the reader with elaborate typographical displays. The best comments aid the understanding of a program by briefly pointing out salient details or by providing a larger-scale view of the proceedings." --Andy -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180321/13e55582/attachment.html> ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-22 0:58 ` Andy Kosela @ 2018-03-22 1:27 ` Larry McVoy 2018-03-22 1:59 ` Bakul Shah ` (2 more replies) 0 siblings, 3 replies; 41+ messages in thread From: Larry McVoy @ 2018-03-22 1:27 UTC (permalink / raw) On Wed, Mar 21, 2018 at 07:58:11PM -0500, Andy Kosela wrote: > They also state: "Comments are meant to help the reader of a program. They > do not help by saying things the code already plainly says, or by > contradicting the code, or by distracting the reader with elaborate > typographical displays. The best comments aid the understanding of a > program by briefly pointing out salient details or by providing a > larger-scale view of the proceedings." I so agree with this. Verbose comments suck. Too many comments suck. Why? Because the code evolves and it's work to evolve the comments as well. Too many comments means they are not maintained and they become incorrect. I *HATE* comments that are not correct, hate that so much that if you did that we would talk, if you kept doing that, you are fired. No comments are MUCH better than incorrect comments. Terseness in comments is good. Comment where it is not obvious what is going on. And maintain the comments like you maintain the code. I agree with Dan (I think) that coding is still a craft and getting the comments right is one of the hardest things to master (and I agree that Unix did it pretty darn well). No comments suck, too much sucks, just right is so darn pleasant. --lm ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-22 1:27 ` Larry McVoy @ 2018-03-22 1:59 ` Bakul Shah 2018-03-22 14:46 ` Steve Simon 2018-03-23 1:31 ` Charles Anthony 2 siblings, 0 replies; 41+ messages in thread From: Bakul Shah @ 2018-03-22 1:59 UTC (permalink / raw) On Mar 21, 2018, at 6:27 PM, Larry McVoy <lm at mcvoy.com> wrote: > > On Wed, Mar 21, 2018 at 07:58:11PM -0500, Andy Kosela wrote: >> They also state: "Comments are meant to help the reader of a program. They >> do not help by saying things the code already plainly says, or by >> contradicting the code, or by distracting the reader with elaborate >> typographical displays. The best comments aid the understanding of a >> program by briefly pointing out salient details or by providing a >> larger-scale view of the proceedings." > > I so agree with this. Verbose comments suck. Too many comments suck. > Why? Because the code evolves and it's work to evolve the comments > as well. Too many comments means they are not maintained and they > become incorrect. > > I *HATE* comments that are not correct, hate that so much that if you did > that we would talk, if you kept doing that, you are fired. No comments > are MUCH better than incorrect comments. > > Terseness in comments is good. Comment where it is not obvious what > is going on. And maintain the comments like you maintain the code. > > I agree with Dan (I think) that coding is still a craft and getting the > comments right is one of the hardest things to master (and I agree that > Unix did it pretty darn well). No comments suck, too much sucks, just > right is so darn pleasant. When reading new code, I initially ignore comments, at least within a function, and just try to figure out what the code does. This is because often people do not update comments. Code has to at least compile so they are forced to update it and hopefully test it but comments.... In the Go language ecosystem they have "go doc" which can pull out comments at different level. Example: go doc io // package level + top level exported declarations go doc io.Copy // function level comments + header go doc io.Reader // interface level + interface body and so on. This does incentivize people to write good comments. This is very handy in that you can see how your comments read when divorced from the code. But notice that no comments within a function are output. [Perhaps IDEs show relevant comments too but I find them too heavyweight and don't use them] A larger point is appropriate documentation, not just source comments. There should be a function spec as well. I used to write a manpage for a command etc. first, especially when someone else has to code it. A manpage is describes the syntax, function, results and errors and links to related manpages. All this usually in a page or two! ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-22 1:27 ` Larry McVoy 2018-03-22 1:59 ` Bakul Shah @ 2018-03-22 14:46 ` Steve Simon 2018-03-22 15:22 ` ron minnich 2018-03-22 16:22 ` Ron Natalie 2018-03-23 1:31 ` Charles Anthony 2 siblings, 2 replies; 41+ messages in thread From: Steve Simon @ 2018-03-22 14:46 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 1717 bytes --] > On 22 Mar 2018, at 01:27, Larry McVoy <lm at mcvoy.com> wrote: > >> On Wed, Mar 21, 2018 at 07:58:11PM -0500, Andy Kosela wrote: >> They also state: "Comments are meant to help the reader of a program. They >> do not help by saying things the code already plainly says, or by >> contradicting the code, or by distracting the reader with elaborate >> typographical displays. The best comments aid the understanding of a >> program by briefly pointing out salient details or by providing a >> larger-scale view of the proceedings." > > I so agree with this. Verbose comments suck. Too many comments suck. > Why? Because the code evolves and it's work to evolve the comments > as well. Too many comments means they are not maintained and they > become incorrect. > > I *HATE* comments that are not correct, hate that so much that if you did > that we would talk, if you kept doing that, you are fired. No comments > are MUCH better than incorrect comments. > > Terseness in comments is good. Comment where it is not obvious what > is going on. And maintain the comments like you maintain the code. > > I agree with Dan (I think) that coding is still a craft and getting the > comments right is one of the hardest things to master (and I agree that > Unix did it pretty darn well). No comments suck, too much sucks, just > right is so darn pleasant. > > --lm on the commenting subject, and as it was Shannon’s anniversary recently... i always felt information theory relates well to comments. i.e. repeating anything i can see from the code (like “returns void”) tells me nothing. telling me something non-obvious (“allocate one more for end of list sentinel”) really helps. -Steve ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-22 14:46 ` Steve Simon @ 2018-03-22 15:22 ` ron minnich 2018-03-22 16:22 ` Ron Natalie 1 sibling, 0 replies; 41+ messages in thread From: ron minnich @ 2018-03-22 15:22 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 2345 bytes --] so if you had an 11/45 with dual RKO5s back in the day with their massive storage capacity, then you had source and your system with source and docs could run out of L2 cache in a modern cheapo IOT board. Now wouldn't that be a hoot. But how would we simulate pulling the RK05 cartridge out of the drive? On Thu, Mar 22, 2018 at 8:05 AM Steve Simon <steve at quintile.net> wrote: > > > > On 22 Mar 2018, at 01:27, Larry McVoy <lm at mcvoy.com> wrote: > > > >> On Wed, Mar 21, 2018 at 07:58:11PM -0500, Andy Kosela wrote: > >> They also state: "Comments are meant to help the reader of a program. > They > >> do not help by saying things the code already plainly says, or by > >> contradicting the code, or by distracting the reader with elaborate > >> typographical displays. The best comments aid the understanding of a > >> program by briefly pointing out salient details or by providing a > >> larger-scale view of the proceedings." > > > > I so agree with this. Verbose comments suck. Too many comments suck. > > Why? Because the code evolves and it's work to evolve the comments > > as well. Too many comments means they are not maintained and they > > become incorrect. > > > > I *HATE* comments that are not correct, hate that so much that if you did > > that we would talk, if you kept doing that, you are fired. No comments > > are MUCH better than incorrect comments. > > > > Terseness in comments is good. Comment where it is not obvious what > > is going on. And maintain the comments like you maintain the code. > > > > I agree with Dan (I think) that coding is still a craft and getting the > > comments right is one of the hardest things to master (and I agree that > > Unix did it pretty darn well). No comments suck, too much sucks, just > > right is so darn pleasant. > > > > --lm > > on the commenting subject, and as it was Shannon’s anniversary recently... > i always felt information theory relates well to comments. > > i.e. repeating anything i can see from the code (like “returns void”) > tells me nothing. > > telling me something non-obvious (“allocate one more for end of list > sentinel”) really helps. > > -Steve > > > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180322/1fcbb6ff/attachment-0001.html> ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-22 14:46 ` Steve Simon 2018-03-22 15:22 ` ron minnich @ 2018-03-22 16:22 ` Ron Natalie 2018-03-22 16:32 ` arnold 2018-03-22 16:33 ` Kurt H Maier 1 sibling, 2 replies; 41+ messages in thread From: Ron Natalie @ 2018-03-22 16:22 UTC (permalink / raw) [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #1: Type: text/plain, Size: 564 bytes --] > i.e. repeating anything i can see from the code (like “returns void”) tells me nothing. It's right up there with using #defines for silly things like #define FOUR 4 Great. What doe this tell me that the literal 4 doesn't. It's a matter of time until someone says #define FOUR 5 I actually found some code in use that had #define notdef 1 in it. I about went through the roof. Frankly, I have immense distaste for the definition NULL. Especially those implementations that try to fix it by introducing a spurious cast on it. ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-22 16:22 ` Ron Natalie @ 2018-03-22 16:32 ` arnold 2018-03-22 20:20 ` Lyndon Nerenberg 2018-03-22 16:33 ` Kurt H Maier 1 sibling, 1 reply; 41+ messages in thread From: arnold @ 2018-03-22 16:32 UTC (permalink / raw) "Ron Natalie" <ron at ronnatalie.com> wrote: > Frankly, I have immense distaste for the definition NULL. Especially > those implementations that try to fix it by introducing a spurious cast > on it. I'll agree with the latter part. But in my own code I try to be very careful to use NULL for pointers, '\0' for end of string, and 0 for numbers. Even though 0 could be used in all three cases, the different forms make it much more clear what the type of data is that I'm working with. My two cents, Arnold ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-22 16:32 ` arnold @ 2018-03-22 20:20 ` Lyndon Nerenberg 0 siblings, 0 replies; 41+ messages in thread From: Lyndon Nerenberg @ 2018-03-22 20:20 UTC (permalink / raw) > I'll agree with the latter part. But in my own code I try to be very > careful to use NULL for pointers, '\0' for end of string, In the '\0' case I have a preference for NUL, but admittedly it's easy to confuse/typo with NULL. That convention follows from my habit of enuming ASCII constants with their three-letter 'names' (e.g. CAN, DLE, ...). --lyndon ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-22 16:22 ` Ron Natalie 2018-03-22 16:32 ` arnold @ 2018-03-22 16:33 ` Kurt H Maier 1 sibling, 0 replies; 41+ messages in thread From: Kurt H Maier @ 2018-03-22 16:33 UTC (permalink / raw) On Thu, Mar 22, 2018 at 12:22:06PM -0400, Ron Natalie wrote: > > It's right up there with using #defines for silly things like > #define FOUR 4 > > Great. What doe this tell me that the literal 4 doesn't. It's a matter of time until someone says > #define FOUR 5 > One of my favorite messages I've ever received: http://sourceware.org/ml/glibc-cvs/2013-q1/msg00115.html khm ^ permalink raw reply [flat|nested] 41+ messages in thread
* [TUHS] Comments in early Unix systems 2018-03-22 1:27 ` Larry McVoy 2018-03-22 1:59 ` Bakul Shah 2018-03-22 14:46 ` Steve Simon @ 2018-03-23 1:31 ` Charles Anthony 2 siblings, 0 replies; 41+ messages in thread From: Charles Anthony @ 2018-03-23 1:31 UTC (permalink / raw) On Wed, Mar 21, 2018 at 6:27 PM, Larry McVoy <lm at mcvoy.com> wrote: > > I *HATE* comments that are not correct, hate that so much that if you did > that we would talk, if you kept doing that, you are fired. No comments > are MUCH better than incorrect comments. > > From "Programming Pearls": "If the code and the comments disagree, they are probably both wrong." -- Charles -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20180322/aba87c4a/attachment.html> ^ permalink raw reply [flat|nested] 41+ messages in thread
end of thread, other threads:[~2018-03-23 1:31 UTC | newest] Thread overview: 41+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2018-03-21 14:17 [TUHS] daemons are not to be exorcised Noel Chiappa 2018-03-21 15:03 ` Clem Cole 2018-03-21 16:18 ` Arthur Krewat 2018-03-21 17:28 ` Paul Winalski 2018-03-21 17:33 ` George Michaelson 2018-03-21 17:50 ` Arthur Krewat 2018-03-21 19:49 ` A. P. Garcia 2018-03-21 19:37 ` Paul Winalski 2018-03-21 17:34 ` Larry McVoy 2018-03-22 2:24 ` Dave Horsfall 2018-03-21 17:39 ` WIlliam Cheswick 2018-03-21 17:52 ` Arthur Krewat 2018-03-21 17:56 ` Nemo 2018-03-21 18:01 ` Larry McVoy 2018-03-21 18:04 ` Dan Cross 2018-03-21 19:56 ` Clem Cole 2018-03-21 20:04 ` [TUHS] comments ( was daemons exorcised ) Earl Baugh 2018-03-21 20:18 ` Paul Winalski 2018-03-21 20:51 ` Ron Natalie 2018-03-21 20:13 ` [TUHS] daemons are not to be exorcised Paul Winalski 2018-03-21 20:28 ` [TUHS] Comments in early Unix systems Warren Toomey 2018-03-21 20:48 ` Ron Natalie 2018-03-21 22:18 ` William Corcoran 2018-03-21 23:02 ` Clem Cole 2018-03-22 1:31 ` Larry McVoy 2018-03-21 23:17 ` Arthur Krewat 2018-03-21 23:50 ` Larry McVoy 2018-03-22 0:55 ` Mike Markowski 2018-03-22 1:00 ` Larry McVoy 2018-03-21 23:45 ` Warner Losh 2018-03-22 0:31 ` Steve Johnson 2018-03-22 0:58 ` Andy Kosela 2018-03-22 1:27 ` Larry McVoy 2018-03-22 1:59 ` Bakul Shah 2018-03-22 14:46 ` Steve Simon 2018-03-22 15:22 ` ron minnich 2018-03-22 16:22 ` Ron Natalie 2018-03-22 16:32 ` arnold 2018-03-22 20:20 ` Lyndon Nerenberg 2018-03-22 16:33 ` Kurt H Maier 2018-03-23 1:31 ` Charles Anthony
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).