[TUHS] Discuss of style and design of computer programs from a user stand point

[TUHS] Discuss of style and design of computer programs from a user stand point

[David]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2174 bytes --]


> From: Michael Kjörling <michael at kjorling.se>
> To: tuhs at minnie.tuhs.org
> Subject: Re: [TUHS] Discuss of style and design of computer programs
> 	from a user stand point
> Message-ID: <20170506091857.GE12539 at yeono.kjorling.se>
> Content-Type: text/plain; charset=utf-8
> 
> I would actually take that one step further: When you are writing
> code, you are _first and foremost_ communicating with whatever human
> will need to read or modify the code later. That human might be you, a
> colleague, or the violent psychopath who knows both where you live and
> where your little kids go to school (might as well be you). You should
> strive to write the code accordingly, _even if_ the odds of the threat
> ever materializing are slim at most. Style matters a lot, there.
> 
Interesting, I was going to say about the same thing about the violent psychopath
who has to maintain your code after you leave. When I lectured at UCSD or was
giving talks on style for ViaSat I always said the same thing:

  Whatever you write, the fellow who is going to wind up maintaining it is a known
  axe killer, now released from prison, completely reformed. He learned computer
  programming on MS/DOS 3.1 and a slightly broken version of Pascal. He will be
  given your home phone number and address so if he has any questions about the
  code you wrote he can get in contact with you.

This always got a few chuckles. I then pointed out that whenever anyone gets code
that someone else wrote, the recipient always thinks that they can ‘clean up’ what
is there because the original author clearly doesn’t understand what proper code
looks like.

Over time, I’ve learned that everyone has a style when writing code, just like handwriting
and given enough time, I can spot who the author of a block of code is just from the
indenting, placement of ( and ) around a statement and other small traits.

What makes good code is the ability to convey the meaning of the algorithm
from the original author to all those who come after. Sometimes even the most
unusual code can be quite clear, while the most cleanly formatted and commented
code can be opaque to all.

	David

[TUHS] Discuss of style and design of computer programs from a user stand point

[Michael Kjörling]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 970 bytes --]

On 7 May 2017 08:58 -0600, from arnold at skeeve.com:
>>> I don't imagine it would be hard to re-write [uniq] to handle utf-8.
>> 
>> It does look like at least GNU coreutils 8.13 uniq is broken in that
>> regard, which frankly surprised me. That version isn't _that_ old.
> 
> Are your LC_* env variables set correctly?

I believe so (I don't recall seeing any other UTF-8-related weirdness
for a very long time), but I would want to verify the behavior on a
system that doesn't have a gazillion customizations accumulated over
years _and_ has the most recent version of coreutils before I file an
actual bug report. (It's not like Debian is ever bleeding edge, to
begin with.) I'll see if I spin up a VM or three one of these days to
check.

-- 
Michael Kjörling • https://michael.kjorling.se • michael at kjorling.se
                 “People who think they know everything really annoy
                 those of us who know we don’t.” (Bjarne Stroustrup)

[TUHS] Discuss of style and design of computer programs from a user stand point

[Warner Losh]

On Sat, May 6, 2017 at 7:42 PM, Noel Hunt <noel.hunt at gmail.com> wrote:
> I was about to suggest using the Plan9 port utilities of the
> same name but it seems 'uniq' is not coded to handle Runes
> (aka utf-8). I don't imagine it would be hard to re-write it to
> handle utf-8.

I guess I should have been clearer on what wouldn't work. It can't
possibly work for Japanese and Chinese where words aren't separated by
whitespace. Would cause problems in hybrid languages where words can
be composed of logograms and sonograms (say Japanese which often use a
few Kanji with hiragana endings that then run into hiragana particles
or other grammar elements). Can't work without modification (using
class names) for Cyrillic because there's no A or Z in words there.
Won't work in any language that has a discontiguous set of letters,
which includes many western european languages since all the accented
or otherwise decorated letters aren't in the range A-Z.

So whether or not the underlying tools can handle UTF-8 encoding,
there are problems with the original.

If you used:

 tr -cs "[:alpha:]" '\n' | tr "[:upper:]" "[:lower:]" | sort | uniq -c
| sort -rn | sed ${1}q

you'd still have issues with languages that don't use word separators,
or write non-alphabetically.

Warner

> On Sun, May 7, 2017 at 11:15 AM, Warner Losh <imp at bsdimp.com> wrote:
>>
>> On Sat, May 6, 2017 at 1:50 PM, Bakul Shah <bakul at bitblocks.com> wrote:
>> > tr -cs A-Za-z '\n' | tr A-Z a-z | sort | uniq -c | sort -rn | sed ${1}q
>>
>> The cool thing about this thread is that I learned two things: what tr
>> -s does, and the Nq does for sed...
>>
>> Sadly, this doesn't work so well for text that isn't ASCII-7 english...
>>
>> Warner
>
>

[TUHS] Discuss of style and design of computer programs from a user stand point

[arnold]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 450 bytes --]

Michael Kjörling <michael at kjorling.se> wrote:

> On 7 May 2017 11:42 +1000, from noel.hunt at gmail.com (Noel Hunt):
> > I don't imagine it would be hard to re-write [uniq] to
> > handle utf-8.
>
> It does look like at least GNU coreutils 8.13 uniq is broken in that
> regard, which frankly surprised me. That version isn't _that_ old.

Are your LC_* env variables set correctly?

If you file a bug report, it should get fixed.

Thanks,

Arnold

[TUHS] Discuss of style and design of computer programs from a user stand point

[Michael Kjörling]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1047 bytes --]

On 7 May 2017 11:42 +1000, from noel.hunt at gmail.com (Noel Hunt):
> I don't imagine it would be hard to re-write [uniq] to
> handle utf-8.

It does look like at least GNU coreutils 8.13 uniq is broken in that
regard, which frankly surprised me. That version isn't _that_ old.

    $ uniq --version
    uniq (GNU coreutils) 8.13
    Copyright (C) 2011 Free Software Foundation, Inc.
    License GPLv3+: GNU GPL version 3 or later
    <http://gnu.org/licenses/gpl.html>.
    This is free software: you are free to change and redistribute it.
    There is NO WARRANTY, to the extent permitted by law.

    Written by Richard M. Stallman and David MacKenzie.
    $ ( echo $'\u1234' ; echo $'\u2345' ; echo $'\u1234' )
    ሴ
    ⍅
    ሴ
    $ ( echo $'\u1234' ; echo $'\u2345' ; echo $'\u1234' ) | uniq
    ሴ
    $

-- 
Michael Kjörling • https://michael.kjorling.se • michael at kjorling.se
                 “People who think they know everything really annoy
                 those of us who know we don’t.” (Bjarne Stroustrup)

[TUHS] Discuss of style and design of computer programs from a user stand point

[Michael Kjörling]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 568 bytes --]

On 7 May 2017 00:06 -0400, from crossd at gmail.com (Dan Cross):
> "Look! You can
> filter and transform this data!" "...but I've been doing that at the shell
> nearly every day for the past quarter of a century...." "...this one goes
> to 11."

"Look! This code can execute code that it creates itself!" "LISP has
been around for a while."

-- 
Michael Kjörling • https://michael.kjorling.se • michael at kjorling.se
                 “People who think they know everything really annoy
                 those of us who know we don’t.” (Bjarne Stroustrup)

[TUHS] Discuss of style and design of computer programs from a user stand point

[Noel Hunt]

I was about to suggest using the Plan9 port utilities of the
same name but it seems 'uniq' is not coded to handle Runes
(aka utf-8). I don't imagine it would be hard to re-write it to
handle utf-8.

On Sun, May 7, 2017 at 11:15 AM, Warner Losh <imp at bsdimp.com> wrote:

> On Sat, May 6, 2017 at 1:50 PM, Bakul Shah <bakul at bitblocks.com> wrote:
> > tr -cs A-Za-z '\n' | tr A-Z a-z | sort | uniq -c | sort -rn | sed ${1}q
>
> The cool thing about this thread is that I learned two things: what tr
> -s does, and the Nq does for sed...
>
> Sadly, this doesn't work so well for text that isn't ASCII-7 english...
>
> Warner
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://minnie.tuhs.org/pipermail/tuhs/attachments/20170507/78dce325/attachment.html>

[TUHS] Discuss of style and design of computer programs from a user stand point

[Warner Losh]

On Sat, May 6, 2017 at 1:50 PM, Bakul Shah <bakul at bitblocks.com> wrote:
> tr -cs A-Za-z '\n' | tr A-Z a-z | sort | uniq -c | sort -rn | sed ${1}q

The cool thing about this thread is that I learned two things: what tr
-s does, and the Nq does for sed...

Sadly, this doesn't work so well for text that isn't ASCII-7 english...

Warner

[TUHS] Discuss of style and design of computer programs from a user stand point

[Bakul Shah]

On Sun, 07 May 2017 04:43:33 +1000 Dave Horsfall <dave at horsfall.org> wrote:
> 
> > I also made the point that "clever" sucks.  At least most of the time. 
> > All "clever" means is "hard to understand".  The brief joy one gets from 
> > clever code is stomped on by the frustration one gets from having to fix 
> > it.

> Apropos the above, I do confess to writing "clever code" from time to time 
> (PERL is a beautiful language for such sins)...
> 
> Of course, in the olden days it was the APL "one-liners" :-)

On the other hand, you have to grok only one line of code
instead reading pages of Java/C++ with surprises lurking
everywhere :-)

Since you need one line to do the work of many many lines of
c++/Java code, you should expect to spend more time on that
one line!

The same is true with shell one liners as well. We don't
(usually) consider constructs such as the following "clever"
because we expect its reader to have a certain level of code
literacy and context (or an ability to gain such).

tr -cs A-Za-z '\n' | tr A-Z a-z | sort | uniq -c | sort -rn | sed ${1}q

[TUHS] Discuss of style and design of computer programs from a user stand point

[Dave Horsfall]

On Sat, 6 May 2017, Larry McVoy wrote:

> When I run engineering teams the point I make is if you wrote the code 
> more than 6 months ago it might as well be someone else's code.  So 
> write it in a way that someone else can debug / extend it.

A principle I've tried to follow over the years is "write code as though 
the next person to maintain it is an axe-wielding murderer who knows where 
you live".

> I also made the point that "clever" sucks.  At least most of the time. 
> All "clever" means is "hard to understand".  The brief joy one gets from 
> clever code is stomped on by the frustration one gets from having to fix 
> it.

Apropos the above, I do confess to writing "clever code" from time to time 
(PERL is a beautiful language for such sins)...

Of course, in the olden days it was the APL "one-liners" :-)

-- 
Dave Horsfall DTM (VK2KFU)  "Those who don't understand security will suffer."

[TUHS] Discuss of style and design of computer programs from a user stand point

[Kurt H Maier]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 956 bytes --]

On Sat, May 06, 2017 at 09:18:57AM +0000, Michael Kjörling wrote:
>
> I would actually take that one step further: When you are writing     
> code, you are _first and foremost_ communicating with whatever human  
> will need to read or modify the code later. 
         
This can be, and is, taken too far.  It is currently fashionable in the
Ruby world to erect testing gantries that look like
       
describe 'service' do
  it 'is listening' do
    expect(port 443).to be_listening
  end
end
       
and then drag in a couple hundred thousand lines of extra code to make  
this cuteness approximate instructions for the computer.
       
It's all well and good to write for the person who comes behind you, but
at some point it will break, and the closer you've flown to this sun the
worse it will be for the poor sod who has to pick up the pieces.  I'd   
take durable code I have to work to understand over fragile artwork     
any day.
       
khm

[TUHS] Discuss of style and design of computer programs from a user stand point

[Larry McVoy]

On Sat, May 06, 2017 at 09:18:57AM +0000, Michael Kj??rling wrote:
> On 5 May 2017 22:33 -0700, from scj at yaccman.com (Steve Johnson):
> > For me, a lot of what
> > I learned was from Stan Brown at the Labs, who read piles of my
> > (atrocious) FORTRAN code and repeatedly pointed out that when you
> > wrote a program, you were not just communicating with the computer,
> > but also other humans (including yourself) who would read (and perhaps
> > modify) the code in the future...
> 
> I would actually take that one step further: When you are writing
> code, you are _first and foremost_ communicating with whatever human
> will need to read or modify the code later. That human might be you, a
> colleague, or the violent psychopath who knows both where you live and
> where your little kids go to school (might as well be you). 

When I run engineering teams the point I make is if you wrote the code
more than 6 months ago it might as well be someone else's code.  So
write it in a way that someone else can debug / extend it.

I also made the point that "clever" sucks.  At least most of the time.
All "clever" means is "hard to understand".  The brief joy one gets 
from clever code is stomped on by the frustration one gets from having
to fix it.  

When they wouldn't listen to that I'd say "I'm the dumbest guy here, right?
And I'm the boss.  And I debug could.  The path to a big bonus does not 
go through clever code".  That seemed to work.

Personally, I find code that is clean, straightforward, obvious to be
beautiful.  The clever stuff usually strikes an odd note, not a good
one.

--lm

[TUHS] Discuss of style and design of computer programs from a user stand point

[Michael Kjörling]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1489 bytes --]

On 6 May 2017 09:09 -0400, from cym224 at gmail.com (Nemo):
>> I would actually take that one step further: When you are writing
>> code, you are _first and foremost_ communicating with whatever human
>> will need to read or modify the code later.
> 
> ..., there are
> times when the code is transformed by optimization into something very
> difficult to read.  (We used noweb to document the transformation.)

True, optimized code can be difficult to read. But very little code
really _needs_ to be optimized to that level, and when you come across
it, you will generally know -- at least after running the application
through a profiler. (I have to admit we do have it easy these days.)

I've been working on optimizing some SQL code recently -- I know,
that's not exactly operating system kernel C or assembler -- and it's
amazing at times how the code can end up being both easier to
understand _as well as_ faster to execute, if you just put some
thought into what the code really needs to do. And not just minor
speedups either, but wallclock runtime reductions on the order of _two
to four nines_.

I think there's been only one time in the last several years when I
have really _needed_ to optimize code to the point that its workings
were not obvious.

-- 
Michael Kjörling • https://michael.kjorling.se • michael at kjorling.se
                 “People who think they know everything really annoy
                 those of us who know we don’t.” (Bjarne Stroustrup)

[TUHS] Discuss of style and design of computer programs from a user stand point

[Nemo]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 532 bytes --]

On 06/05/2017, Michael Kjörling <michael at kjorling.se> wrote:
> I would actually take that one step further: When you are writing
> code, you are _first and foremost_ communicating with whatever human
> will need to read or modify the code later.

Something similar appears in the front of almost every Wirth book
(though sometimes honoured in the breach).  That being said, there are
times when the code is transformed by optimization into something very
difficult to read.  (We used noweb to document the transformation.)

N.

[TUHS] Discuss of style and design of computer programs from a user stand point

[Michael Kjörling]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2578 bytes --]

On 5 May 2017 22:33 -0700, from scj at yaccman.com (Steve Johnson):
> For me, a lot of what
> I learned was from Stan Brown at the Labs, who read piles of my
> (atrocious) FORTRAN code and repeatedly pointed out that when you
> wrote a program, you were not just communicating with the computer,
> but also other humans (including yourself) who would read (and perhaps
> modify) the code in the future...

I would actually take that one step further: When you are writing
code, you are _first and foremost_ communicating with whatever human
will need to read or modify the code later. That human might be you, a
colleague, or the violent psychopath who knows both where you live and
where your little kids go to school (might as well be you). You should
strive to write the code accordingly, _even if_ the odds of the threat
ever materializing are slim at most. Style matters a lot, there.

Sure, some code really needs to be heavily optimized, and might end up
obscure for it. In operating systems, interrupt routines are probably
one of the major candidates, but first stage bootloaders need their
fair share of it too for other reasons. Tight loops or code that needs
to be able to operate on lots of data quickly are other examples. But
_most code isn't like that_ and can allow for some extra verbosity and
some performance penalty if that means making it significantly easier
to read and modify. That's not to say code should be verbose _just
because_, but if you don't need ultimate performance, I say aim for
readability and modifyability first; processing and memory usage
second. You can always go back and optimize bits that turn out to need
it.

And of course, I find Doug McIlroy's shell snippet mentioned by Noel
interesting, _because I did something very similar not all that long
ago_; in my case, stringing together a bunch of shell tools to get a
list of all URLs from an e-mail message for further processing.
(Something like a composable _urlview_; if urlview had even had a
"dump to stdout" option, that would have done all I needed it for.)
Works like a charm, and isn't even terribly complicated. It could
probably be done in a single line of perl or awk instead of piping
through a grand total of six commands, but that's okay. And of course,
stringing together a bunch of commands was the first approach that
occured to me...

-- 
Michael Kjörling • https://michael.kjorling.se • michael at kjorling.se
                 “People who think they know everything really annoy
                 those of us who know we don’t.” (Bjarne Stroustrup)