Friday Finking: Source code organisation

[Chris Angelico]

On Tue, Dec 31, 2019 at 3:08 AM Barry Scott <barry at barrys-emacs.org> wrote:
>
>
>
> > On 30 Dec 2019, at 15:35, Chris Angelico <rosuav at gmail.com> wrote:
> >
> > On Tue, Dec 31, 2019 at 1:47 AM Barry Scott <barry at barrys-emacs.org> wrote:
> >>
> >>
> >>
> >>> On 28 Dec 2019, at 22:49, Chris Angelico <rosuav at gmail.com> wrote:
> >>>
> >>> On Sun, Dec 29, 2019 at 9:37 AM DL Neil via Python-list
> >>> <python-list at python.org> wrote:
> >>>>
> >>>> Is it helpful to, and thus, do you have a style/convention for ordering
> >>>> the methods within each class in your code?
> >>>>
> >>>> A major difference however, is that if our mythical collection of
> >>>> module-functions has an internal-reference, eg b() requires a(), then
> >>>> function a() MUST exist, ie be defined, 'before' function b(). Whereas a
> >>>> class's methods may be defined in any (complete) sequence.
> >>>>
> >>>> So, do you have an orderly method [hah!] for presenting/locating
> >>>> class-methods (and module-functions) within your code?
> >>>>
> >>>> - why bother, the editor does 'the heavy lifting'
> >>>> - dunders to the fore
> >>>> - alphanumeric sequence by name
> >>>> - order of appearance/use in 'mainline code'
> >>>> - as they sprang to mind during TDD-creation
> >>>> - most-used first, least-used last
> >>>> - my code 'at the top', their stuff later...
> >>>> - names of Monty Python characters by TV appearance date
> >>>> or,
> >>>> - some combination of ideas
> >>>> and,
> >>>> - how do you vary the above when dependencies intrude?
> >>>>
> >>>
> >>> "Define before use" is a broad principle that I try to follow, even
> >>> when the code itself doesn't mandate this. This generally means that
> >>> "if name is main" is the very last thing in the file, and if there's a
> >>> main() function or equivalent, that's usually just before that. Any
> >>> metaprogramming goes right at the top; sometimes this is mandated (if
> >>> I write a decorator function, it has to be above the functions it's
> >>> decorating), but even if it's not, metaprogramming goes before the
> >>> mainline.
> >>
> >>
> >>
> >> "define before use" is basically email top-posting for code isn't it?
> >
> > Kinda the opposite - it means that you get the context before you get
> > something that refers to it.
>
> But its not context its the low level detail that I should be able to ignore
> when trying to understand the goals of the code. I'll only need to know
> about the lower level detail if I have a need to change the code.
>
> Another analogy would ne how a journalist writes a story. You can take
> a well written article and stop reading at any point, but still know what
> the story is about. The more paragraphs you read the more informed
> you are about the story. (Editors exploit this property of a story to shorten
> it if it does not fit on the page).
>

Sure, but that's not what top-posting in emails is like. With a
top-posted reply, truncation means you lack context; with the
journalistic style of "front-load the important info", truncation
means you lack detail. So in coding, I would say the journalistic
style corresponds to a broad notion of "first docstring, then main
function, then support code", which is an absolutely legit way to do
things (but not my preferred way).

ChrisA