Re: [DNG] Readable code; making code more easily writable; Emacs, multifiles-apmod; VUE; Code Bubbles; Lisp; Inform 7; HyperCard and HyperTalk - was Re: "Common knowledge?"-question

[Steve Litt]

On Mon, 25 Jan 2016 17:56:04 -0500
Apollia  wrote:

> On Sun, Jan 24, 2016 at 4:08 PM, Rainer Weikusat <
> rainerweiku...@virginmedia.com> wrote:  
> 
> > Apollia  writes:
> >
> > [...]
> >  
> > > I think if I ever did code much in C, my code would end up
> > > looking very unusual and unconventional to many people, because I
> > > often like to use long, descriptive names for functions and
> > > variables, no matter what language I'm using, even Bash.  
> >
> > This style isn't really uncommon for people used to IDEs doing
> > identifier auto-completion. But that's not only a bitch to work with
> > without it but also difficult to read because of the sheer
> > verbosity of the text. Eg, using an identifier
> >
> > combined-list-of-files-in-all-source-folders
> >
> > doesn't really communicate more than 'all-files' or even just
> > 'all' (if the files is evident from the context) would.
> >  
> 
> Thanks for the feedback!  Perhaps as I get more comfortable with
> programming in general I'll stop relying so much on the crutch of
> overly verbose names.  I know I overdo it to some extent.

One man's opinion: Names explaining exact action and purpose are a good
thing. If your names are too long, cast a critical eye toward your
design. If the word "and" appears in a name, that's a dead bang
giveaway that something's wrong with the design.

SteveT

Steve Litt 
January 2016 featured book: Twenty Eight Tales of Troubleshooting
http://www.troubleshooters.com/28


___
Dng mailing list
Dng@lists.dyne.org
https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng

Re: [DNG] Readable code; making code more easily writable; Emacs, multifiles-apmod; VUE; Code Bubbles; Lisp; Inform 7; HyperCard and HyperTalk - was Re: "Common knowledge?"-question

[Rainer Weikusat]

Steve Litt  writes:
> Apollia  wrote:
>>>  wrote:  

[...]

 I often like to use long, descriptive names for functions and
  variables, no matter what language I'm using, even Bash.

[...]

>>>  using an identifier combined-list-of-files-in-all-source-folders
>>> doesn't really communicate more than 'all-files' or even just 'all'
>>> (if the files is evident from the context) would.
>> 
>> Thanks for the feedback!  Perhaps as I get more comfortable with
>> programming in general I'll stop relying so much on the crutch of
>> overly verbose names.  I know I overdo it to some extent.
>
> One man's opinion: Names explaining exact action and purpose are a
> good thing.

That's almost a truism. But "explaining exact action and purpose" isn't
necessarily something better accomplished by using longer names. Eg,
assuming I define a structure supposed to be part of a linked list, I
usually start that as

struct something {
struct something *p;

if it doesn't contain anything else which naturally suggests itself for
the name 'the pointer'. p is a good name for a pointer and the context
is supposed to supply the information re: what 'the pointer'
specifically refers to. In the example above, it would obviously be 'the
link pointer'.

One could argue that such a convention should be documented in some kind
of 'the style explained' guide but apart from that, there's nothing
wrong with it.
___
Dng mailing list
Dng@lists.dyne.org
https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng

Re: [DNG] Readable code; making code more easily writable; Emacs, multifiles-apmod; VUE; Code Bubbles; Lisp; Inform 7; HyperCard and HyperTalk - was Re: "Common knowledge?"-question

[Rainer Weikusat]

Apollia  writes:
> Rainer Weikusat  wrote:
>
>> Apollia  writes:

[...]

>>> I often like to use long, descriptive names for functions and
>>> variables,

[...]

>> combined-list-of-files-in-all-source-folders
>>
>> doesn't really communicate more than 'all-files' or even just 'all' (if
>> the files is evident from the context) would.
>
> Thanks for the feedback!  Perhaps as I get more comfortable with
> programming in general I'll stop relying so much on the crutch of overly
> verbose names.  I know I overdo it to some extent.
>
> But another thing I like about long, unique, non-generic names is that
> when doing searches, I can more easily find definitely related pieces
> of code, and avoid finding a lot of unrelated pieces of code which
> just happen to use the same generic variable names like "x" or "all".

[...]

A pretty complicated way to express "I think I'm right and you're
wrong." (supposed to apply to all of the text, it took me a few hours to
think through that), however "So do I.".

[next paragraph is a paraphrase of a part of the kernel CodingStyle
document I consider to be 'generally sensible' in this respect]

On it's own a word (or even a phrase) is meaningless. It's always
supposed to be understood in a certain context. Applied to naming in
programs, this means one should consider using rather short names if
there's a lot of context, eg, for local variables, and longer ones if
they have to stand on their own, eg, public functions or global
variables.

[followed by my own, insignificant opinion]

There should be no reason to do global searches for local names. That's
a bit like cutting up people in order to determine what food they
apparently like. In an expression,

combined-list-of-files-in-all-source-folders

is very unwieldly. Imagine this as

(if
  (<= 
(-
  (* number-of-files-in-all-source-folders
average-number-of-lines-per-file-in-source-folders)
  (* number-of-files-in-all-letter-folders
 average-number-of-lines-per-file-in-letter-folders)))
   'write-some-more-code-in-future
   'reply-to-a-few-letters)

[the first silly contrived example I could come up with]

Almost all of this is letters of names and the code itself is dwarfed by
them. But the names, no matter how expressive, only communicate intent
and not facts. And that's also a lot of text to express very little, ie,
a program written in this way will either end up being of epic
proportions or accomplish very little.
___
Dng mailing list
Dng@lists.dyne.org
https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng

Re: [DNG] Readable code; making code more easily writable; Emacs, multifiles-apmod; VUE; Code Bubbles; Lisp; Inform 7; HyperCard and HyperTalk - was Re: "Common knowledge?"-question

[Apollia]

On Sun, Jan 24, 2016 at 4:08 PM, Rainer Weikusat <
rainerweiku...@virginmedia.com> wrote:

> Apollia  writes:
>
> [...]
>
> > I think if I ever did code much in C, my code would end up looking very
> > unusual and unconventional to many people, because I often like to use
> > long, descriptive names for functions and variables, no matter what
> > language I'm using, even Bash.
>
> This style isn't really uncommon for people used to IDEs doing
> identifier auto-completion. But that's not only a bitch to work with
> without it but also difficult to read because of the sheer verbosity of
> the text. Eg, using an identifier
>
> combined-list-of-files-in-all-source-folders
>
> doesn't really communicate more than 'all-files' or even just 'all' (if
> the files is evident from the context) would.
>

Thanks for the feedback!  Perhaps as I get more comfortable with
programming in general I'll stop relying so much on the crutch of overly
verbose names.  I know I overdo it to some extent.

But another thing I like about long, unique, non-generic names is that when
doing searches, I can more easily find definitely related pieces of code,
and avoid finding a lot of unrelated pieces of code which just happen to
use the same generic variable names like "x" or "all".


If I were a painter instead of a coder, perhaps I might be more of an
impressionist than a realist or a minimalist.  But even that might be too
complimentary of my style. :-)  Rather than impressionist, I'm maybe more
of a hasty, impatient finger-painter specializing in abstract blobs. :-)
Or a caricaturist who exaggerates many things ridiculously. :-)

But, hopefully I'll learn to do better after plenty more practice, and
continuing to strive to learn as much as I can from wiser and more
knowledgeable people than me, such as you and probably everyone here.

I'm probably going to go back to being mostly quiet now since I can't think
of much else of interest to add.

But, thanks to you and everyone for all your fascinating, very educational
posts, and all the wonderful work you're all doing on Devuan!

Best wishes,
Apollia
___
Dng mailing list
Dng@lists.dyne.org
https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng

Re: [DNG] Readable code; making code more easily writable; Emacs, multifiles-apmod; VUE; Code Bubbles; Lisp; Inform 7; HyperCard and HyperTalk - was Re: "Common knowledge?"-question

[Rainer Weikusat]

Apollia  writes:

[...]

> I think if I ever did code much in C, my code would end up looking very
> unusual and unconventional to many people, because I often like to use
> long, descriptive names for functions and variables, no matter what
> language I'm using, even Bash.

This style isn't really uncommon for people used to IDEs doing
identifier auto-completion. But that's not only a bitch to work with
without it but also difficult to read because of the sheer verbosity of
the text. Eg, using an identifier

combined-list-of-files-in-all-source-folders

doesn't really communicate more than 'all-files' or even just 'all' (if
the files is evident from the context) would.
___
Dng mailing list
Dng@lists.dyne.org
https://mailinglists.dyne.org/cgi-bin/mailman/listinfo/dng

[DNG] Readable code; making code more easily writable; Emacs, multifiles-apmod; VUE; Code Bubbles; Lisp; Inform 7; HyperCard and HyperTalk - was Re: "Common knowledge?"-question

[Apollia]

On Fri, Jan 22, 2016 at 4:34 PM, Rainer Weikusat <
rainerweiku...@virginmedia.com> wrote:

> Can the effect of the following C function
>
> static void print_start(char const *name, char const *what)
> {
> char *buf, *p;
> unsigned name_len, what_len, total;
>
> name_len = strlen(name);
> what_len = strlen(what);
> total = name_len + what_len + 3;
>
> p = buf = alloca(total);
> memcpy(p, name, name_len);
> p += name_len;
> *p++ = ' ';
> memcpy(p, what, what_len);
> p += what_len;
> *p++ = ':';
> *p = ' ';
>
> *buf &= ~0x20;
>
> Write(2, buf, total);
> }
>
> be considered obvious or should it rather get an explanation?
>
> An ASCII lowercase letter can be turned into the corresponding uppercase
> letter by clearing the sixth bit.
>

I'm quite inexperienced with C, so I don't understand that function at all,
despite having some experience with PHP, Perl, JavaScript, SQL, Bash, Emacs
Lisp, Python, and various other things.

I find it so mind-boggling I can't make any very specific suggestions for
how to make it more understandable.

But, I definitely agree with adding explanations, and others' suggestions
also sound good to me (though I'm probably not really qualified to judge).


Anyway, the rest of my message is going to consist of hopefully
interesting/useful tangents related to the topics of making code more
readable, and more easily writable.


I think if I ever did code much in C, my code would end up looking very
unusual and unconventional to many people, because I often like to use
long, descriptive names for functions and variables, no matter what
language I'm using, even Bash.

Ideally I'd like to make my scripts as readable/understandable as plain
English.  (Not that I constantly strive for that - it's often too much
work.)


Here's one recent example of my perhaps rather strange coding style - an
Emacs add-on I modified a lot.  (Actually, maybe a better example would be
the even more recent shell scripts I've been working on for my Puppy Linux
Setup Kit, but those aren't done yet.)

https://github.com/Apollia/multifiles-apmod.el/blob/master/multifiles-apmod.el

https://github.com/Apollia/multifiles-apmod.el

And here's the original add-on's source code (not by me):

https://github.com/magnars/multifiles.el/blob/master/multifiles.el

(If anyone has any comments, criticism, tips, etc., on multifiles-apmod or
any other topics, I'd be interested to read them, even via private email if
they're too off-topic for the mailing list.)


Actually, I think at the moment, multifiles-apmod is probably the best
already-useable thing I worked on that I can contribute to Devuan.  (At
least until I finish some of my other projects...)

multifiles-apmod, Emacs (which I finally started seriously using almost 3
months ago), and the many other great Emacs add-ons I've installed, have
all made my programming hobby tremendously easier and more enjoyable.

Even my former favorite text editors (Notepad++ and Geany)  were slowing me
down and getting in my way, because I had so many separate files in
different tabs to work on that it was becoming quite a nuisance having to
click tabs all the time, and struggle to remember what files I put things
in, or do searches.

And bookmarks in Notepad++ and Geany (as far as I know) don't let you jump
to locations in different files - only the current file you're working on.

But now, with multifiles-apmod, I can work on numerous separate files all
in a single large buffer.  I can quickly and easily get an overview of my
entire projects just by scrolling around, and I can jump from file to file
by pressing Ctrl-Page Up or Ctrl-Page Down.

And I found 3 different bookmark add-ons for Emacs that I like. :-)


multifiles-apmod definitely has some problems (as you can read in the
readme, or the giant comments section at the top of the source code), and
I'm still very inexperienced with Emacs and Emacs Lisp - but, nonetheless,
multfiles-apmod has still been very useful to me, and has already saved me
a lot of time and frustration.

So, since multifiles-apmod, Emacs, etc. have done me so much good, I just
thought I'd mention them, in case they might help anyone here too.

https://github.com/Apollia/multifiles-apmod.el


Another thing that helps me code is the VUE concept mapping software:
http://vue.tufts.edu/

I use it for making notes, flow charts, documentation, etc.

I sometimes wish I could use VUE as a GUI for editing my actual code.  But,
that's not possible (yet?).

The only thing I've heard of so far which can do something like that is a
Java program called Code Bubbles - which I haven't tried yet, since it
might only be for editing Java code, and I mostly haven't done much of
anything with Java code yet.

http://cs.brown.edu/~spr/codebubbles/


Emacs recently reawakened my curiosity about Lisp, which was originally
piqued years ago by Paul Graham's articles on Lisp:

http://www.paulgraham.com/lisp.html

I never got far