Win a copy of Testing JavaScript Applications this week in the HTML Pages with CSS and JavaScript forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Bear Bibeault
  • Ron McLeod
  • Jeanne Boyarsky
  • Paul Clapham
Sheriffs:
  • Tim Cooke
  • Liutauras Vilda
  • Junilu Lacar
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Tim Holloway
  • fred rosenberger
  • salvin francis
Bartenders:
  • Piet Souris
  • Frits Walraven
  • Carey Brown

Self-Documenting Code

 
Ranch Hand
Posts: 111
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Paul,
I appreciate your comments on picking better names for my variables and I will attempt to do so in the future, but there is another related issue that I wanted your opinion on.
I just completed an assignment where I found myself building more complex constructs (e.g. method(method(array)..etc.).
While this certainly does exploit the power of this language, it doesn't exactly make the code readily understandble. What is your opinion on complex vs. simple constructions or to put it another way efficiency vs. understandability?
 
Sheriff
Posts: 6920
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Well, I'm not Paul, but I would always vote for understandability first, and efficiency second. You know you'll have to understand it, but you don't know if it needs to be more efficient until you test it.
But be careful. Writing readable code is not as easy as it seems. Keep in mind at all times that the main aim is to write code which expresses your intentions as clearly as possible. Make good use of class, variable and method names as well as program structure. Decide on a format convention (I recommend the one described on this site) and stick to it. Don't comment the obvious, and make the code obvious wherever you can. Where you really can't make it obvious, add a comment.
If you have any (short) examples of code which you are not entirely happy with, why not post them here for comments and suggestions?
 
Trailboss
Posts: 23216
IntelliJ IDE Firefox Browser Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Frank makes a good me
Readability first, efficiency second.
Examples would be good.
(sorry for the brevity - work is demanding all my time this week)
 
Betty Reynolds
Ranch Hand
Posts: 111
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Here are some examples from 1.4
1) In the main method:
System.out.println( wordsToSay( args, ...)
as an example of method(method( parm1, ..)
2) In a method I wrote called wordsToSay there are more examples.

...
returnVal.append( commonProc( workBuffer ) + " million ")
...
as an example of one of many statements of the form
method( method( stringBuffer).
The method wordsToSay invokes the method commonProc in buiding
up the appropriate string concatenations that will eventually be returned to main for printing.
I use alot of constructions like this in this assignment. Since I wrote them I know what they do and it appears to cut down on the coding considerably, but would it be clear to others?
 
paul wheaton
Trailboss
Posts: 23216
IntelliJ IDE Firefox Browser Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Well, I think the stuff you just put here isn't very clear. Probably because they are out of context.
I think the way to writing clear code is to do code reviews. When you send code to someone else, that person can tell you how easy or how difficult your stuff is to read. Perhaps you could ask some of the other students, or Frank, to review your program as well and ask for their comments.
I appreciate your considering future students and not posting your solution here.
If you want to understand more about self documenting code, I suggest that you read the Refactoring book by Fowler. Go to www.javaranch.com/books.html to read my book reviews.
 
Frank Carver
Sheriff
Posts: 6920
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
If you want to email me your full solution, I'm happy to look at it for you.
 
Betty Reynolds
Ranch Hand
Posts: 111
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I'd like to, but I don't know your e-mail address. Perhaps Paul can e-mail it to me (I don't want to post mine here).
 
We find this kind of rampant individuality very disturbing. But not this tiny ad:
Building a Better World in your Backyard by Paul Wheaton and Shawn Klassen-Koop
https://coderanch.com/wiki/718759/books/Building-World-Backyard-Paul-Wheaton
    Bookmark Topic Watch Topic
  • New Topic