Home » Eclipse Projects » Eclipse Platform » feature proposal: source code layering
| feature proposal: source code layering [message #181018] |
Fri, 16 January 2004 09:01  |
Eclipse User |
|
|
|
Originally posted by: thats4you.gmx.net
I am using the eclipse IDE as well as Microsoft's .NET IDE, which has the
possibility to define regions within the source code in order to hide
"irrelevant" parts of the code. This is not a bad idea, but I think it
could be done better. Since in Java we are used to write the documentation
directly into the source file using JavaDoc, the source code is more
difficult to read with all these extra lines. Wouldn't it be a good idea
to add the possibility to define layers within the source code? With
layers one could hide the documentation lines while debugging for example.
It could also be useful when one is writing J2EE compatible code for
JBoss. All comment lines, which are just instructing XDoclet could be
hidden while coding.
I would appreciate feedback from other Java programmers :-)
Martin Unterholzner
|
|
| | | |
| Re: feature proposal: source code layering [message #182091 is a reply to message #181230] |
Mon, 19 January 2004 13:52  |
| Eclipse User |
|
|
|
Originally posted by: eclipse-user.jibeinc.com
Rob Williams wrote:
> I like it. Sounds much better than just collapsing individual nodes
> which is tedious. Make it possible to define rules about what goes in
> each layer, then have simple checkboxes for whether a layer is visible
> or not. Not sure that hiding JavaDoc is the main thing that people want
> when they go this route though, it's more likely when classes start
> getting big, it makes it easier to ignore implementation-level stuff to
> get a better handle on interface. Of course, one of the biggest problems
> with programming is that things often grow out of control and a
> mechanism like this may only enable that behavior.
I have to strongly agree with your final assertion there. If tools make
it easier and painless to write bad code, you can be sure that a large
portion of programmers will (continue to) write bad code.
IMO, the tool should encourage good habits, not bad ones. Code folding
encourages the construction of large classes and methods; that is, in
general, a bad habit. Yes, it helps when you have to browse code that
can't be changed - but I'm still skeptical of the feature because I know
most developers will use it to ignore their warts rather than fix them.
Eric
--
Eric Rizzo
Software Architect
Jibe, Inc.
http://www.jibeinc.com
|
|
|
| Re: feature proposal: source code layering [message #183994 is a reply to message #182091] |
Fri, 23 January 2004 10:03 |
| Eclipse User |
|
|
|
Originally posted by: thats4you.gmx.net
Eric Rizzo wrote:
> Rob Williams wrote:
> > I like it. Sounds much better than just collapsing individual nodes
> > which is tedious. Make it possible to define rules about what goes in
> > each layer, then have simple checkboxes for whether a layer is visible
> > or not. Not sure that hiding JavaDoc is the main thing that people want
> > when they go this route though, it's more likely when classes start
> > getting big, it makes it easier to ignore implementation-level stuff to
> > get a better handle on interface. Of course, one of the biggest problems
> > with programming is that things often grow out of control and a
> > mechanism like this may only enable that behavior.
> I have to strongly agree with your final assertion there. If tools make
> it easier and painless to write bad code, you can be sure that a large
> portion of programmers will (continue to) write bad code.
> IMO, the tool should encourage good habits, not bad ones. Code folding
> encourages the construction of large classes and methods; that is, in
> general, a bad habit. Yes, it helps when you have to browse code that
> can't be changed - but I'm still skeptical of the feature because I know
> most developers will use it to ignore their warts rather than fix them.
> Eric
You may be right with your warning. However, I see the problem similar
with argumentations regarding the support of multiple inheritance in
programming languages. Most people fear powerful tools will be abused and
we will end up having messy code. However, my opinion is that proper usage
of tools will always heavily depend on the abilities of the programmer. It
is an open question and there is of course a risk, but should we renounce
some powerful tools because some bad coders will write worse code using
them?
|
|
|
| Re: feature proposal: source code layering [message #184010 is a reply to message #181230] |
Fri, 23 January 2004 10:58 |
| Eclipse User |
|
|
|
Originally posted by: mbrozowski.nc.rr.com
The big reason for a feature like this to enable one to keep all the
information about the code together with the code with the need for everyone
to see it and make the code impossible to use. XDoclet makes EJB writing
MUCH easier but it does make the code harder to find. I'm not sure that
large files are a problem as much as large methods and unweildy logic are.
This would be a great feature that would enable all sorts of other
applications. For exaple a crazy idea would be an application that allows
someone that takes the time to learn the code to add a kind of explanatory
annotation (like director's commentary on a DVD). These annotations could
explain the why behind certain design decisions or code snippets that would
make it easier to get people up to speed in the code and understanding of
the underlying philosophy and make the quicker and better contributors.
This could just go in a 'layer' that was off by default, a sort of
'begginer' mode. Associating these with the code itself allows them to be
updated as the code is because they are closely associated and easily
updated as someone changes it.
Laughs, ok.. now back to reality... I think this would be a cool feature
too..
Matt Brozowski
"Rob Williams" <robwms63@yahoo.com> wrote in message
news:bu98tk$b3e$1@eclipse.org...
> I like it. Sounds much better than just collapsing individual nodes
> which is tedious. Make it possible to define rules about what goes in
> each layer, then have simple checkboxes for whether a layer is visible
> or not. Not sure that hiding JavaDoc is the main thing that people want
> when they go this route though, it's more likely when classes start
> getting big, it makes it easier to ignore implementation-level stuff to
> get a better handle on interface. Of course, one of the biggest problems
> with programming is that things often grow out of control and a
> mechanism like this may only enable that behavior.
>
> Martin Unterholzner wrote:
>
> > I am using the eclipse IDE as well as Microsoft's .NET IDE, which has
the
> > possibility to define regions within the source code in order to hide
> > "irrelevant" parts of the code. This is not a bad idea, but I think it
> > could be done better. Since in Java we are used to write the
documentation
> > directly into the source file using JavaDoc, the source code is more
> > difficult to read with all these extra lines. Wouldn't it be a good idea
> > to add the possibility to define layers within the source code? With
> > layers one could hide the documentation lines while debugging for
example.
> > It could also be useful when one is writing J2EE compatible code for
> > JBoss. All comment lines, which are just instructing XDoclet could be
> > hidden while coding.
> >
> > I would appreciate feedback from other Java programmers :-)
> >
> > Martin Unterholzner
> >
|
|
|
| Re: feature proposal: source code layering [message #184059 is a reply to message #183994] |
Fri, 23 January 2004 12:19 |
| Eclipse User |
|
|
|
As someone who includes extensive Javadoc and comments throughout their
code, I would benefit greatly from folding. Personally I have no use for
the folding of actual code, but the ability to hide my long comment blocks
would ease code comprehension and avert one needless source of distraction
when I am engaged in deep analytical thought. Javadoc is great, but
because it breaks up code continuity, I sometimes feel I might as well be
trying to grok someone's awful Perl script. ;-)
I do agree that it's beneficial to keep Java a "safe" language in certain
areas, and that this design philosophy is part of why Java is more
productive and robust than C++ in general. But on the subject of code
folding -- an *IDE* feature mind you, we're not talking about core
language features here -- why punish programmers who have good programming
practices (i.e. those who copiously document their code) by depriving them
of a valuable tool to facilitate those practices, all because of how a few
programmers with poor programming practices might misuse it?
I think on the balance, the benefits of this feature would far outweigh
the perceived abuses.
On Fri, 23 Jan 2004 15:03:52 +0000 (UTC), Martin Unterholzner
<thats4you@gmx.net> wrote:
> Eric Rizzo wrote:
>
>> Rob Williams wrote:
>
>> > I like it. Sounds much better than just collapsing individual nodes
>> > which is tedious. Make it possible to define rules about what goes in
>> > each layer, then have simple checkboxes for whether a layer is visible
>> > or not. Not sure that hiding JavaDoc is the main thing that people
>> want
>> > when they go this route though, it's more likely when classes start
>> > getting big, it makes it easier to ignore implementation-level stuff
>> to
>> > get a better handle on interface. Of course, one of the biggest
>> problems
>> > with programming is that things often grow out of control and a
>> > mechanism like this may only enable that behavior.
>
>> I have to strongly agree with your final assertion there. If tools make
>> it easier and painless to write bad code, you can be sure that a large
>> portion of programmers will (continue to) write bad code.
>> IMO, the tool should encourage good habits, not bad ones. Code folding
>> encourages the construction of large classes and methods; that is, in
>> general, a bad habit. Yes, it helps when you have to browse code that
>> can't be changed - but I'm still skeptical of the feature because I know
>> most developers will use it to ignore their warts rather than fix them.
>
>> Eric
>
> You may be right with your warning. However, I see the problem similar
> with argumentations regarding the support of multiple inheritance in
> programming languages. Most people fear powerful tools will be abused and
> we will end up having messy code. However, my opinion is that proper
> usage
> of tools will always heavily depend on the abilities of the programmer.
> It
> is an open question and there is of course a risk, but should we renounce
> some powerful tools because some bad coders will write worse code using
> them?
>
|
|
| | |
| Re: feature proposal: source code layering [message #184078 is a reply to message #184073] |
Fri, 23 January 2004 12:37 |
| Eclipse User |
|
|
|
Originally posted by: schmidt.2002.gmx.de
On Fri, 23 Jan 2004 12:34:26 -0500, Andreas Schmidt <schmidt.2002@gmx.de>
wrote:
> On Fri, 23 Jan 2004 11:19:52 -0600, R.U. Deranged
> <yes_this_is_a_real_address@earthlink.net> wrote:
>
>> language features here -- why punish programmers who have good
>> programming practices (i.e. those who copiously document their code) by
>> depriving them of a valuable tool to facilitate those practices, all
>> because of how a few programmers with poor programming practices might
>> misuse it?
>
> This is maybe offtopic, but not everyone thinks that writing extensive
> comments is good programmer's practice. Martin Fowler counts it as one
> of the "bad smells" in programming (see his book "Refactoring"). He
> argues that code should be self-explanatory, with lots of small methods
> carrying the information on what they do exactly in their name (for
> example Entry[] getEntriesSortedByDate()), and variables with
> well-chosen names etc. Then, you would not need long comments anymore.
>
> Andi
Don't get me wrong: Code folding would be useful in any case.
As long as it's not there, you could set a very light gray for comments,
so that the eye is not too much distracted by them!
Andi
|
|
|
| Re: feature proposal: source code layering [message #184091 is a reply to message #184073] |
Fri, 23 January 2004 13:10 |
| Eclipse User |
|
|
|
Mr. Fowler's assertion seems based on an overly-narrow assumption of the
contents of the Javadoc/comment blocks.
Most of my documentation is not necessarily explaining what the code is
doing, but *why* it is doing it. For example, for a method which
implements a particular portion of some obscure protocol specification, I
will add a comment addressing how that aspect of the protocol is
interpreted and why it is needed. This provides a higher-level perspective
on that particular area of the application. Perhaps it isn't always
necessary, but it can be helpful.
In addition to the use of documentation for informative purposes, there
are also functional uses of comments, such as instrumentation for certain
preprocessor-based implementations of design by contract. These don't need
to be visible all the time.
Comments have many uses. Mr. Fowler's views on this subject give me a
"guru smell". ;-)
On Fri, 23 Jan 2004 12:34:26 -0500, Andreas Schmidt <schmidt.2002@gmx.de>
wrote:
> On Fri, 23 Jan 2004 11:19:52 -0600, R.U. Deranged
> <yes_this_is_a_real_address@earthlink.net> wrote:
>
>> language features here -- why punish programmers who have good
>> programming practices (i.e. those who copiously document their code) by
>> depriving them of a valuable tool to facilitate those practices, all
>> because of how a few programmers with poor programming practices might
>> misuse it?
>
> This is maybe offtopic, but not everyone thinks that writing extensive
> comments is good programmer's practice. Martin Fowler counts it as one
> of the "bad smells" in programming (see his book "Refactoring"). He
> argues that code should be self-explanatory, with lots of small methods
> carrying the information on what they do exactly in their name (for
> example Entry[] getEntriesSortedByDate()), and variables with
> well-chosen names etc. Then, you would not need long comments anymore.
>
> Andi
|
|
|
| Re: feature proposal: source code layering [message #184946 is a reply to message #184059] |
Mon, 26 January 2004 10:16 |
| Eclipse User |
|
|
|
Originally posted by: thats4you.gmx.net
R.U. Deranged wrote:
> As someone who includes extensive Javadoc and comments throughout their
> code, I would benefit greatly from folding. Personally I have no use for
> the folding of actual code, but the ability to hide my long comment blocks
> would ease code comprehension and avert one needless source of distraction
> when I am engaged in deep analytical thought. Javadoc is great, but
> because it breaks up code continuity, I sometimes feel I might as well be
> trying to grok someone's awful Perl script. ;-)
> I do agree that it's beneficial to keep Java a "safe" language in certain
> areas, and that this design philosophy is part of why Java is more
> productive and robust than C++ in general. But on the subject of code
> folding -- an *IDE* feature mind you, we're not talking about core
> language features here -- why punish programmers who have good programming
> practices (i.e. those who copiously document their code) by depriving them
> of a valuable tool to facilitate those practices, all because of how a few
> programmers with poor programming practices might misuse it?
> I think on the balance, the benefits of this feature would far outweigh
> the perceived abuses.
I just would like to clarify what I wrote and what was misunderstood. I
wrote the term "layering source code", but what I actually ment was
layering the source code file which includes comments and javadoc-like
documentation. Thus, the primary purpose of such a tool would be
separating code from comments and documentation.
Martin Unterholzner
|
|
|
| Re: feature proposal: source code layering [message #184986 is a reply to message #184073] |
Mon, 26 January 2004 10:48 |
| Eclipse User |
|
|
|
Originally posted by: thats4you.gmx.net
> This is maybe offtopic, but not everyone thinks that writing extensive
> comments is good programmer's practice. Martin Fowler counts it as one of
> the "bad smells" in programming (see his book "Refactoring"). He argues
> that code should be self-explanatory, with lots of small methods carrying
> the information on what they do exactly in their name (for example Entry[]
> getEntriesSortedByDate()), and variables with well-chosen names etc. Then,
> you would not need long comments anymore.
> Andi
Your statement is not offtopic. I know Martin Fowler's point of view and I
partly agree with him: comments are a smell for refactoring and, if it is
possible to make the code more intention-revealing, one should do that.
However, we all know that in a complex program with complex class
inheritance trees even the easiest code will not protect you from getting
something wrong at the first look. In such cases warning comments are
useful when you look at code written by someone else or old code written
by oneself. However, such comments can become annoying when I am used to
the code and when I just want to debug code or fix some bugs.
Now I would like to mention another possible purpose of such a tool. I
recently learned about aspect oriented programming (AspectJ) in java.
Since aspects are stored in their own files, when you look at your classes
you no longer see the complete source code as it gets compiled. This could
result in some surprising bugs. Eclipse helps you by showing you where an
aspect is to be included in your code before it gets compiled.
Why not using the proposed layering tool to support us in the future when
we all do aspect oriented programming? The tool could just inline the code
contained in the aspects as a read-only layer in my java code and show me
the complete source code. In this way it would be easier to debug programs
which contain aspects.
Martin Unterholzner
|
|
| | |
| Re: feature proposal: source code layering [message #185449 is a reply to message #184091] |
Tue, 27 January 2004 10:05 |
| Eclipse User |
|
|
|
Originally posted by: eclipse-user.jibeinc.com
R.U. Deranged wrote:
> Mr. Fowler's assertion seems based on an overly-narrow assumption of the
> contents of the Javadoc/comment blocks.
>
> Most of my documentation is not necessarily explaining what the code is
> doing, but *why* it is doing it. For example, for a method which
> implements a particular portion of some obscure protocol specification,
> I will add a comment addressing how that aspect of the protocol is
> interpreted and why it is needed. This provides a higher-level
> perspective on that particular area of the application. Perhaps it isn't
> always necessary, but it can be helpful.
That is a very valid point, but the thinking is that the vast majority
of JavaDoc comments could be replaced with sound coding techniques, such
as better method and variable names, more modularaization/breakdown,
following the principle of each class/method does one thing and one
thing only, etc.
The case where a comment is useful to explain a complicated algorithm or
design decision that may not be obvious is definitely the minority,
wouldn't you agree? And wouldn't you agree that someone as smart as
Fowler would not advocate a unilateral policy that was not
flexible...he's talking about the general case and I'm sure he
recognizes that there are some valid places for comments...
> In addition to the use of documentation for informative purposes, there
> are also functional uses of comments, such as instrumentation for
> certain preprocessor-based implementations of design by contract. These
> don't need to be visible all the time.
True, they don't. Again, however, I think those types of uses are the
minority (just trying to explain Fowler's and others' position on comments).
Eric
--
Eric Rizzo
Software Architect
Jibe, Inc.
http://www.jibeinc.com
|
|
|
| Re: feature proposal: source code layering [message #185584 is a reply to message #185449] |
Tue, 27 January 2004 12:33 |
| Eclipse User |
|
|
|
On Tue, 27 Jan 2004 10:05:22 -0500, Eric Rizzo <eclipse-user@jibeinc.com>
wrote:
> R.U. Deranged wrote:
>
>> Mr. Fowler's assertion seems based on an overly-narrow assumption of
>> the contents of the Javadoc/comment blocks.
>>
>> Most of my documentation is not necessarily explaining what the code is
>> doing, but *why* it is doing it. For example, for a method which
>> implements a particular portion of some obscure protocol specification,
>> I will add a comment addressing how that aspect of the protocol is
>> interpreted and why it is needed. This provides a higher-level
>> perspective on that particular area of the application. Perhaps it
>> isn't always necessary, but it can be helpful.
>
> That is a very valid point, but the thinking is that the vast majority
> of JavaDoc comments could be replaced with sound coding techniques, such
> as better method and variable names, more modularaization/breakdown,
> following the principle of each class/method does one thing and one
> thing only, etc.
> The case where a comment is useful to explain a complicated algorithm or
> design decision that may not be obvious is definitely the minority,
> wouldn't you agree? And wouldn't you agree that someone as smart as
> Fowler would not advocate a unilateral policy that was not
> flexible...he's talking about the general case and I'm sure he
> recognizes that there are some valid places for comments...
You're correct. I dug out the book in question and he does in fact make
mention of the kinds of valid uses I speak of, if only briefly. I also
agree that my hypothetical scenarios are not commonly encountered.
Nevertheless, that does not negate the usefulness of a code folding
feature for when such situations do arise.
Even if you weren't to encounter any of these rarer cases, one major
justification for thorough code commenting still remains: providing
Javadocs for library APIs. I for one am grateful for the JDK API docs for
instance, which of course are maintained as Javadocs, many of them quite
detailed and lengthy. I would be rather disturbed if one of the project
managers at Sun decided they should refactor those Javadoc comments into
extinction. ;-)
>> In addition to the use of documentation for informative purposes, there
>> are also functional uses of comments, such as instrumentation for
>> certain preprocessor-based implementations of design by contract. These
>> don't need to be visible all the time.
>
> True, they don't. Again, however, I think those types of uses are the
> minority (just trying to explain Fowler's and others' position on
> comments).
>
> Eric
|
|
| |
| Re: feature proposal: source code layering [message #185760 is a reply to message #185707] |
Tue, 27 January 2004 16:41 |
| Eclipse User |
|
|
|
On Tue, 27 Jan 2004 15:39:21 -0500, Scott Stanchfield <scott@javadude.com>
wrote:
> In article <opr2f22eg8bc47nv@news.eclipse.org>,
> yes_this_is_a_real_address@earthlink.net says...
>> You're correct. I dug out the book in question and he does in fact make
>> mention of the kinds of valid uses I speak of, if only briefly.
>
> This is why he listed it as a "smell" as opposed to a "problem" or
> "antipattern". Think of smells as warning flags that should cause you to
> take a critical look at something. They don't automatically mean
> something it wrong, just potentially suspicious...
>
> -- Scott
Yes, hence the "guru smell" I sensed instead of a "clueless egomaniacal
amateur alert". ;-)
|
|
|
Goto Forum:
Current Time: Thu Aug 21 04:23:44 EDT 2025
Powered by FUDForum. Page generated in 0.34442 seconds |
Home