Re: [ppig-discuss] Rhetorical structure of code: Anyone interested in collaborating?

[Raoul Duke]

> No doubt it could be construed as either-or rather than both-and.  Having 
> relevant media to support professional development is necessary. However, it 
> seems rather too easy to end up with a cultural reduction toward the 
> technological means rather than the ends (and thus we end up mantras). 
> Personally, I find it useful to keep the big picture in mind. The development 
> of professional practices are not something that businesses are particularly 
> good at, in my opinion.


I don't disagree too much I am guessing. I agree most practices suck.
I want things to start with Good Developers and Good Processes. But if
I am one of those people who is practicing such things, I would like
the computational power we have in abundance to help me outsource the
things in my head to the system, so that it can be maintained (and
searched and mined and used to generate tests and etc.) long term. And
if the tools aren't there to help people latch on to good ways of
doing things, then they will have more opportunity to not do it less
badly. I mean, good people should be able to ignore bad tools. But
good tools should not be eschewed or prevented from existing.



> The subject of language choice continues the themes of description & signing 
> and interpretative complexity with respect to the constraints and affordances 
> of the language and its expected uses.  We seem to muddle on by with rather 
> overly complicated syntax by virtue of the knowledge that certain languages 
> are generally applied to specific domains (text parsing, html processing).



The muddling goes on is for many reasons, unfortunately.

The stuff that might be used to encode the relationships among things
in our ASCII source code might be a different programming / markup
language, so it might be a chance to do at least that niche better.
Who knows.



> Again, I would stress that the structure is not inherent to the language, but 
> rather is mediated through its use.  What we do with a language at the level 
> of action and the (desirable) craft-object of concern dictate the subjective 
> complexity. I think a useful distinction is being made between the means of 
> partitioning a problem and implementing it (the use of a language) in 
> distinction to a means to visualise artefacts derived from the language. If 
> the visualisation tool helps one to enlarge the scope of the object of 
> concern then it is also acting to specifically scope the approach (which may 
> be fine, but is worth recognising).


Model driven design and all that jazz is something I suspect a lot of
people wish really did work. I suspect we don't think our structure is
inherent in the language at all. To me the original question clearly
was about how the structure is unfortunately mediated and obscured
through the use of a given programming language?



> For me, these issues were clearly exemplified with windows based approach to 
> programming.  By providing ease of use in one area, one makes it harder in 
> others. Hence it is possible to undermine skills in design and organisation 
> by introducing short-cuts in an attempt to change the landscape of a problem 
> (thereby setting oneself up for more adventurous problems in the future).



Yes and no. E.g., just because one limited set of visual metaphors
stopped at some arbitrary brick wall doesn't mean:
a) that we should give up on visual approaches cf. Eve programming environment
b) that we cannot marry the 2 cf. Smalltalk GUI, or Linux, Mac
offering both windowed & terminal environments, with some minimal
communication being supported back and forth between the two

I don't see why it has to be a zero sum game *in the long run*, if
there are enough intelligent & caring people who want to tackle it.
Admittedly that is a different thing than what pragmatically has
happened for whatever business or social reasons to date.

-- 
You received this message because you are subscribed to the Google Groups "PPIG 
Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to ppig-discuss+unsubscr...@googlegroups.com.
To post to this group, send an email to ppig-discuss@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [ppig-discuss] Rhetorical structure of code: Anyone interested in collaborating?

[Huw Lloyd]

Hi Raoul,

No doubt it could be construed as either-or rather than both-and.  Having
relevant media to support professional development is necessary. However,
it seems rather too easy to end up with a cultural reduction toward the
technological means rather than the ends (and thus we end up mantras).
Personally, I find it useful to keep the big picture in mind. The
development of professional practices are not something that businesses are
particularly good at, in my opinion.

The subject of language choice continues the themes of description &
signing and interpretative complexity with respect to the constraints and
affordances of the language and its expected uses.  We seem to muddle on by
with rather overly complicated syntax by virtue of the knowledge that
certain languages are generally applied to specific domains (text parsing,
html processing).

Again, I would stress that the structure is not inherent to the language,
but rather is mediated through its use.  What we do with a language at the
level of action and the (desirable) craft-object of concern dictate the
subjective complexity. I think a useful distinction is being made between
the means of partitioning a problem and implementing it (the use of a
language) in distinction to a means to visualise artefacts derived from the
language. If the visualisation tool helps one to enlarge the scope of the
object of concern then it is also acting to specifically scope the approach
(which may be fine, but is worth recognising).

For me, these issues were clearly exemplified with windows based approach
to programming.  By providing ease of use in one area, one makes it harder
in others. Hence it is possible to undermine skills in design and
organisation by introducing short-cuts in an attempt to change the
landscape of a problem (thereby setting oneself up for more adventurous
problems in the future).

Best,
Huw


On 2 May 2016 at 20:13, Raoul Duke  wrote:

> Personally, I would place value on the development of these
> organisational / design skills rather than certain means to achieve them.
> Note that these originate as professional / ethical concerns rather than of
> any given business or organisation. I would be wary of the valuation of
> visualisation tools etc, as a means of postponing addressing good design
> (new silver-bullet merchandise) . Similarly, devoting time to describing
> the structure of code will certainly help with a reflexive appreciation for
> such structural concerns.
>
>
>
> That kinda reads to me like an either/or thing that is setting up 2
> different sides and purporting they can't get along. And that the setup is
> due to misconstruing the way in which tools can and should be used. (I
> mean, why don't we all go back to machine code, otherwise?)
>
> For me, the point is that if there are good things to do, then it would be
> even better if our systems helped to do those good things, and to refify
> them and encode them in the system. That way other people and my future
> selves can look at the system and understand it as much as possible, so
> that there is less reliance on the cultural memory around the code. Not
> because I devalue cultural memory, but because I think it is important in
> many ways to have backups, alternatives, and supports for the cultural
> memory.
>
> sincerely.
>
> --
> You received this message because you are subscribed to the Google Groups
> "PPIG Discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to ppig-discuss+unsubscr...@googlegroups.com.
> To post to this group, send email to ppig-discuss@googlegroups.com.
>
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups "PPIG 
Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to ppig-discuss+unsubscr...@googlegroups.com.
To post to this group, send an email to ppig-discuss@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [ppig-discuss] Rhetorical structure of code: Anyone interested in collaborating?

[Dan Sumption]

>
> To me, a 1000-line module is a God Class. A 3000-line module is a complete
>> disaster.
>>
>> Accepted best practice is that a file too big to view on your screen is
>> too long. Optimum file size is probably under 30 lines.
>>
> Really?  I've heard that said about *function* size, but not about
> *module* size.
>

Really. *File* size. One should be able to view, and make sense of, an
entire file. On one screen.

Functions should be even smaller, IMO no more than five lines. Ideally one.

Quoting from my bible for software development, Clean Code -
http://amzn.to/1VWmzEV

*The first rule of classes is that they should be small. The second rule of
classes is that they should be smaller than that. No, we're not going to
repeat exactly the same text from the Functions chapter. But as with
functions, smaller is the primary rule when it comes to designing classes.
As with functions, our immediate question is always "How small?"*

When you work on code, work on a single piece of functionality at a time.
The open file is your workbench. It should mesh well with your working
memory.

Admittedly this creates another type of complexity: the complexity of many
files. That should be tackled through appropriate naming and structuring of
files and packages: itself a (very) difficult challenge, perhaps the most
difficult challenge in software development. But not the same challenge as
writing clear, concise, functioning code.

I just checked the Java 1.6 library source release.
> 7195 *.java files.
> > summary(d)
>   min = 9, 1st quartile = 55, median = 112, mean = 288.2,
>   3rd quartile = 286, max = 9604.
>

"We've always done it this way" rarely means the same thing as "this is the
best way to do it". And in my experience Java is *never* the right place to
start when looking for examples of well-written code.

By and large, the people who wrote these four different
> systems were experienced and capable programmers
> following practices that were adequate for developing
> systems that would be used by huge numbers of other
> programmers a long period.
>
> If large modules were *necessarily* a disaster, these systems
> would not be so successful.
>

Large files aren't *necessarily* a disaster.

If there are people out there who are capable enough, macho enough, to
wrestle a 10,000 line file into something that works, I applaud them.

That doesn't make working with perilously large files any easier.


> I don't think I've ever seen a *non-trivial* class that would fit on a
> screen
>

I really hate that phrase "non-trivial". It came up a lot recently in
relation to the NPM left-pad fiasco, along with statements like "have we
all forgotten how to program?"

Small does not mean trivial. Small, single responsibility classes are
perhaps the most useful and the most reusable.

Programmers should not be forced to reinvent the wheel all of the time,
re-writing left-pad on a monthly basis, just to prove that they are Real
Programmers.

Rather than "trivial" I would say "building block". Rather than
"non-trivial" I would say "*composed of* building blocks (composed of
building blocks (composed of building blocks (...))).

Even then, I struggle to conceive of a case where a 1,000 line file could
>> be broken down into 7 clear, comprehensible concepts.
>>
> You seem to be talking about a major rewrite, which I'm not.
>

I'm talking about *Single Responsibility Principle*.
https://en.wikipedia.org/wiki/Single_responsibility_principle

If you are modifying a file, that's because its responsibility has changed.

To understand the impact of your changes to that file, you need to have
clear in your mind *everything that the file does*.

If it's a 10 line file, that's relatively easy. If it's a 1,000 line file,
good luck!

Dan Sumption

-- 
You received this message because you are subscribed to the Google Groups "PPIG 
Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to ppig-discuss+unsubscr...@googlegroups.com.
To post to this group, send an email to ppig-discuss@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [ppig-discuss] Rhetorical structure of code: Anyone interested in collaborating?

[Richard A. O'Keefe]

On 28/04/16 7:15 PM, Dan Sumption wrote:
This is a subject that interests me greatly, and I'm keen to hear 
people's views on it.


My perspective is that of a working software developer (albeit with a 
background in psychology), not an academic. I have no experience of 
ML, and have worked only a little with functional languages.


I was a little taken aback by this line in the original post:

Why can't I see the structure in a 3000-line module, or even
a 1000-line module? 



To me, a 1000-line module is a God Class. A 3000-line module is a 
complete disaster.


Accepted best practice is that a file too big to view on your screen 
is too long. Optimum file size is probably under 30 lines.
Really?  I've heard that said about *function* size, but not about 
*module* size.


I just checked the Java 1.6 library source release.
7195 *.java files.
> summary(d)
  min = 9, 1st quartile = 55, median = 112, mean = 288.2,
  3rd quartile = 286, max = 9604.

Looking at the source code for the SML/NJ library, and excluding
files in .cm directories, there are
1121 *.sml files.
> summary(d)
  min = 1, 1st quartile = 36, median = 80, mean = 194.5,
  3rd quartile = 180, max = 10040
There were 29 files with >= 1000 lines.
The sizes are lower than the Java files because of the absence of
anything like JavaDoc and the paucity of other comments.

Looking at the Erlang 18.2 release, there are
7315 *.[hye]rl files.
> summary(d)
  min = 0, 1st quartile = 35, median = 135, mean = 481.4,
  3rd quartile = 420, max = 32020
I believe the superlarge file there was machine-generated.
There were 788 files with >= 1000 lines.

Looking at the Python 3.4.4 release, there were
1740 *.py files.
> summary(d)
  min = 0, 1st quartile = 53, median = 169, mean = 383.5,
  3rd quartile = 429, max = 6413.
There were 160 files with >= 1000 lines.

By and large, the people who wrote these four different
systems were experienced and capable programmers
following practices that were adequate for developing
systems that would be used by huge numbers of other
programmers a long period.

If large modules were *necessarily* a disaster, these systems
would not be so successful.

I have quite a few other large projects handy, but one has to
stop *somewhere*.  The take-home point is that far from being
disastrous scary monsters, large modules are *common*

I don't think I've ever seen a *non-trivial* class that would fit on a 
screen,

at least not one with comments.  I've seen way too many Java classes
that could do practically nothing and you couldn't even *begin* to
understand them in isolation; the result of splitting things up into tiny
pieces in the service of an unrealistic dogma was spaghetti tangles of
objects with complex interactions.

Breaking a 3000 line module into 30-line pieces would simply make
things worse: you'd probably end up with a lot more than 100 pieces
and the pieces would be no more readable without their context
than they were *with* their context.  Overall, the code would be
HARDER to read.  Not hypothetical:  more than once I've rewritten
a tangle of small pieces sprayed across several directories into one
file with (for me) a drastic improvement in readability.

In the case of the FileName class I mentioned, putting the two files
that define it together means the *class* is 815 SLOC, but the
average *method* is 4.5 SLOC, one line for header and 3.5 lines
for body.
Chunking strategies, allowing an entire module to be thought of as 
7+/-2 concepts, will certainly help.

It will help some things, but not others.
This is arguably what Smalltalk method categories and C# regions are about.

However, this assumes that there is one right way to chunk things
and that there are no "cross-cutting" relationships.


Even then, I struggle to conceive of a case where a 1,000 line file 
could be broken down into 7 clear, comprehensible concepts.

You seem to be talking about a major rewrite, which I'm not.
You also seem to be assuming that large modules aren't *already*
divided into topics, and that "clear comprehensible concepts"
aren't connected by relationships that are not immediately obvious
from the code.

Most of the large modules I've looked at *are* divided into chunks of
some sort, but the reason they are single files is that the chunks are
for some good reason tightly coupled.




--
You received this message because you are subscribed to the Google Groups "PPIG 
Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to ppig-discuss+unsubscr...@googlegroups.com.
To post to this group, send an email to ppig-discuss@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [ppig-discuss] Rhetorical structure of code: Anyone interested in collaborating?

[Mark Levison]

I'm still a practitioner, to the extent a consultant can be.

Visualations need to be derived from the code and not the annotations since
I've never met a programmer who voluntary updated their JavaDoc or other
annotation.

I've seen literate code on rare occasions, mostly from teams doing BDD/TDD.
Even those teams have had rough edges.

Cheers
Mark


On Apr 28, 2016 7:01 PM,  wrote:

> Richard,
>
>> I've been thinking for some time of writing a paper with the
>> title "Why can't I see the structure?" based on the idea that
>> modules in every programming language I know look like blobs.
>
> The most obvious answer is lack of practice:
>
http://shape-of-code.coding-guidelines.com/2016/03/24/habits-are-the-peripheral-vision-of-the-mind/

The answer is obvious, simple, and wrong.

I'm talking about languages I've had *LOTS* of practice in.
I may be an academic, but I spend a lot of time reading and
writing code.  And not enough time writing papers, sigh.
But at least when I talk to students about programming I am talking about
something I put a good deal of time into.

In the last year I wrote about 30 kSLOC.

I've had responses from practitioners that they see the same
problem.


--
You received this message because you are subscribed to the Google Groups
"PPIG Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to ppig-discuss+unsubscr...@googlegroups.com.
To post to this group, send an email to ppig-discuss@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

-- 
You received this message because you are subscribed to the Google Groups "PPIG 
Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to ppig-discuss+unsubscr...@googlegroups.com.
To post to this group, send an email to ppig-discuss@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [ppig-discuss] Rhetorical structure of code: Anyone interested in collaborating?

[Gergely Buday]

I  am not sure if it matters for you but how about Standard ML modules?

- Gergely

On Thursday, 28 April 2016, Richard A. O'Keefe  wrote:

> I've been thinking for some time of writing a paper with the
> title "Why can't I see the structure?" based on the idea that
> modules in every programming language I know look like blobs.
> I'm aware of visual notations like UML, BON, SDL, and what
> was it, Visual Erlang?  But for me, those are just spaghetti
> with meatballs; once you get beyond just a handful of boxes
> in your diagram, all diagrams look much the same.  In any
> case, I'm interested in the medium scale.
>
> Why can't I see the structure in a 3000-line module, or even
> a 1000-line module?  (I am not asserting that Erlang is
> particularly bad here.  It isn't.)
>
> The kind of structure I'm interested in can, I think, be
> described as *rhetorical* structure, like relationships
> between paragraphs.
>
> My *belief* is that if this structure were made explicit,
> perhaps by textual structure, perhaps by annotations, perhaps
> by some graphical form (but probably derived from annotations),
> it would be easier to understand medium-sized wodges of code.
>
> I'm aware of annotation support in languages like Java and C#
> and for that matter, Smalltalk, but with the exception of
> Smalltalk, nobody seems to be using annotations in this way
> (and that exception is me).
>
> I'd be very interested in hearing from anyone else who has been
> thinking in this area.
>
>
> --
> You received this message because you are subscribed to the Google Groups
> "PPIG Discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to ppig-discuss+unsubscr...@googlegroups.com.
> To post to this group, send an email to ppig-discuss@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups "PPIG 
Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to ppig-discuss+unsubscr...@googlegroups.com.
To post to this group, send an email to ppig-discuss@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.