new DIP47: Outlining member functions of aggregates

[Bruno Medeiros]

On 09/09/2013 04:46, Manu wrote:
> Missed the action...
>
> Well it's clear this is not a popular proposal.
> And even to me personally, it's certainly not of critical importance. If
> there was a single thing I'd like to see *DONE* in D, it would be
> temporary/r-value->ref args, without question (really, really annoying
> to work around).
>
> For the record, I tend to agree with the arguments of many in the
> 'against' camp *from a purist point of view*, but the problem remains,
> and the reason I raised it; this has demonstrated to me and my
> colleagues on a number of occasions that it is a consistent productivity
> hindrance.
> I guess a significant reason my experience seems to differ from
> many(/most) on this forum, is that they're not in the business of
> banging out quick throw-away commercial code.
> The practical reality in my experience in the games industry is this:
>   - Some (perhaps small) percentage of code is tech/foundation code. It
> is carefully authored, but still typically documented only of the class
> outline in the header file isn't already self-explanatory (I'm a big fan
> of self-documenting code). It is to be re-used.
>   - Much (perhaps most) code is rudimentary logic and glue code, or
> 'game code' as we call it. This tends to be code that is written by more
> inexperienced programmers and written to tight schedules. It is almost
> never documented (apart from the occasional inline comments), rarely
> conforms to some spec (unless it's implementing from foundational
> interface), and usually exists to serve only the life of this one very
> specific project, ie, throw-away. It is also almost always
> logic-intensive code, riddled with switch/if/else constructs that take
> an awful lot of vertical space, which further magnifies the problem of
> inline function definitions breaking up the readability of the class
> outline.
>
> Now further, from an absolutely practical point of view, the time that
> someone unfamiliar with this code has to deal with it in the first place
> is very likely at 11pm the night before the publisher is demanding a
> build so they can show it to a bunch of arseholes in fancy suits who
> will decide if they're going to pay us or not.
> In C++ there is a very useful tool for unfamiliar programmers to get a
> good brief overview of the code before they go hacking at it, that is
> the class outline.
> We've lost that. And I have demonstrably missed it.
>
> People make claims like "write better code, split it up better, document
> your code better, use the IDE folding", blah blah, but it's simply not
> the practical reality. The budget and schedule does not typically allow
> for careful consideration, design, and documentation of such throw away
> code which glues the project together.
> The code is what it is, and whether it's written in C++, or D, or lua,
> it's probably not going to change the nature of this huge volume of
> crappy code.
> Code folding doesn't work in foreign editors, communication tools, diff
> windows; code reviews become more time consuming to approve, and I don't
> know many programmers that like/use it regardless, even if it may help
> in some occasions.
> I think it's bat-shit-crazy to rely on a tool to simply make code
> readable and easy to understand for a start. I also personally feel code
> folding alienates me from the code I'm writing. As an author, you
> quickly gain a feel for the layout of your source file; the flow and
> shape of the code across the file is kinda picturesque. For me
> personally, code folding ruins that relationship with my code, and I
> don't like it. It makes it harder for me to sweep through my file and
> quickly locate the points of interest that I'm working through. So if
> I'm not using it in my own code, but I'm required to use it to
> understand someone else's code... there's a bit of a conflict of
> interest there.
>
> If I'm one of very few voices in favour of class outlines, I'm going to
> suggest letting this argument sleep until other more serious issues are
> resolved which people have been waiting on for ages.
> I certainly want r-values -> ref args to work much more.
>
> Keep in mind, I raised this debate as a practical account of last
> weekend, among a bunch of other issues which were certainly more
> significant than this one, but this seemed to capture the most attention.
> It's not the first time it's come up and it'll be back again I'm sure :)
>
> I support this DIP, obviously, but I'd suggest perhaps a conservative
> restriction that definitions should only be allowed to appear within the
> same module as the declaration. This would seem to simplify things like
> mangling issues and access rights. In my own use case, I have no reason
> to spread definitions across files. I just want to see class outlines
> clearly summarised at the top of the file. This saves time, and time is
> money.
>
>
> On 8 September 2013 03:00, Walter Bright <newshound2 at digitalmars.com
> <mailto:newshound2 at digitalmars.com>> wrote:
>
>     Outlining of member functions is the practice of placing the
>     declaration of a member function in the struct/class/union, and
>     placing the definition of it at global scope in the module or even
>     in another module.
>
>     http://wiki.dlang.org/DIP47
>
>

Ok, basically you are trying to add some language complexity just to 
help with the use case where you can't, or is not convenient, to use an 
IDE. (communication tools, diff viewers, etc.)
I don't agree with this DIP then. Let' see:
A) does this use case merit these languages changes?
B) is this proposal short-sighted in what it improves?

Regarding point B, I think that is the case. Reviewing code outside of 
an IDE is always going to be a limiting experience. (you don't see 
compilation errors/warnings, you can't do open definition, you can't see 
documentation hovers, etc.) And some of these limits you cannot 
work-around by making changes to the language and the code of your 
project. Consider this example, imagine you want to see the outline of a 
class (signatures of the members), like you sugest, but including the 
members of superclasses *as well* (this is a feature supported by some 
IDEs, and fairly useful for large hierarchical classes). How would you 
address this with a language feature? You can't, unless you want your 
DIP to allow the source class outline to include the superclass member 
signatures as well, but that would just be an insane amount of bloat and 
code duplication. :S


BTW, some IDEs (JDT for example) support semantic functionality (code 
complete, etc) in their diff viewers, at least if one of the sides you 
are comparing with is your workspace code.

-- 
Bruno Medeiros - Software Engineer