After running Sonar on one of my project I get a violation for 'trailing comments'. So I wonder, is this purely related to accepted/recommended code layout conventions for Java or is there 'more to it'? What's the reasoning behind it? When I'm looking over some C++ code ( recent Doom code review, there are tons (or binder full of) trailing comments.
From the famous book Code Complete:
The comments have to be aligned so that they do not interfere with the visual structure of the code. If you don't align them neatly, they'll make your listing look like it's been through a washing machine.
Endline comments tend to be hard to format. It takes time to align them. Such time is not spent learning more about the code; it's dedicated solely to the tedious task of pressing the spacebar or tab key.
Endline comments are also hard to maintain. If the code on any line containing an endline comment grows, it bumps the comment farther out, and all the other endline comments will have to bumped out to match. Styles that are hard to maintain aren't maintained.
Endline comments also tend to be cryptic. The right side of the line doesn't offer much room and the desire to keep the comment on one line means the comment must be short. Work then goes into making the line as short as possible instead of as clear as possible. The comment usually ends up as cryptic as possible.
A systemic problem with endline comments is that it's hard to write a meaningful comment for one line of code. Most endline comments just repeat the line of code, which hurts more than it helps.
Having said that, it's also about one's choice about coding style. I would personally avoid trailing comments as they don't help that much.
Just because something has trailing comments doesn't mean they're good. Also bear in mind that Doom 3's code is ~10 years old, and coding styles change over time.
In general, trailing comments indicate that a line of code cannot stand on its own. And, in general, that's a code smell, because a single line of code should be fairly transparent.
Looking through some of the source I don't actually see a ton of trailing comments, though I see a lot of methods that are too long, and a lot of comments in the middle of functions.
Those often indicate the following code deserves its own method.
I would argue that yes, there's more to it, and the "more" is communication and clarity.
Trailing comments are nothing bad per se. However, you should write your code as clearly as possible so that you don't have to explain your code line by line using comments. That's why some people consider trailing code comments as a hint that the code is not understandable enough.
See also the Java Style Guide for more information about that.
Related
On these screenshots, you can see the difference between indent size.
The first one it's the default Code Style provided by Idea:
And the second one it's a Google Java Code Style (I renamed it a little but it's the same default file):
The second screen clearly shows that the indents a smaller in a half.
What's the point in reducing them? And the second question is, how can I undo this modification by modifying the file?
To allow long lines become shorter to make more free room on small screens.
The original 4 spaces indentation was intentionally introduced with the design of java (whereas the indentation of C/C++ was normally less), for a better overview and in order to punish too much nesting of blocks, using more sub-methods. And indeed this indentation does not hurt.
Google's later Java code style is an actionistic reform, which such a huge player like Google can push.
For a regular indention of code of 4 indents it would save only 8 characters.
This has minor effect when also considering the length of field/variable/method names.
So I would call the Google style hubris, a mistake for a language which has strong conventions. Other languages have more variations, especially on placement of parentheses and on spacing.
But one should adapt to the convention of the one of both, that is used in the firm. Google's style did not generally replace the old style, even though Android is a huge part on Google's home turf.
Why using labels in Java is a bad practice? I cant find a reason. All explanations - you shouldn't use it just because you shouldn't.
It's difficult to read code containing breaks to a label. Also, a label can be accidentally moved, or code inserted at an incorrect location with respect to a label. The compiler is not able to warn you of these effects since the code remains syntactically valid.
Code that's difficult to read is difficult to maintain. Bugs will inevitably creep in.
Other control structures (break, continue, while, for, etc.) don't suffer from this.
Note that a switch to a label doesn't suffer from these effects either: the structure of a switch block is well-defined.
The most sensible alternative to breaking out of a nested loop is to recast the code to a function and use return. You also get the added benefit of being able (potentially) to return a value back to the caller.
I think that you are referring to break and continue labeled.
The problem is that labeled break (and continue) is a construct of imperative languages that is absolutely not related to Object Oriented.
In Object Oriented programs the flows can be easily understood. It is not possible to jump from a part of code to another part of code, you can only call a method or continue current code or exit the current block of code.
Jumping from position to position is a probable point of break for your application where bugs can easily happens. Jumping creates what is called spaghetti code
Labelled breaks (and breaks, in a smaller way) are a more-modern equivalent to the old GOTO statements of older languages (FORTRAN, COBOL, Basic). Goto statements were found to be much more liable to contain an error than all other kinds of statements combined -- the study I'm remembering measured it as 9 times more likely. This gave rise to the "structured programming" movement in the 70s, and the banning of the goto statement from some software shops at the time.
It is more important to be able to read code easily than to be able to write it without restrictions.
Labels are fine to break out of nested for-loops. I'd suggest to put the nested loops in a separate method and then break out with return.
The problem is that the complex flows of processing becomes really hard to follow.
I've just read about spaghetti code ( wiki link) that "goto" statement creates, I wonder if label in java makes spaghetti code?
I just interested in this because one of my old question about break and label in java that I asked here
Labels are so rarely needed/used that no, not really. Also you can't jump to a label, you need to break to it, so you can't get the similar kind of confusion as with filling the code with goto whereever statements.
The main problem with labels is that they are rarely used which means they are surprising and possibly confusing for a reader. e.g
http://stackoverflow.com/
System.out.println("Hello SO");
At first glance, that doesn't even look like valid Java code, but it is.
Because labels tend to be used only when the are really needed, and sometime not used when they should have been used IMHO, they don't lead to spaghetti code in Java in reality.
I am trying to learn proper code formatting in Java, the conventions, keeping it neat and putting proper comments.
I am baffled, however, on what wording I should use when I call for a JOptionPane input dialog in order to 'receive' a user-specified value.
What is normally used in this situation?
I am using "// Get user input", but I just read an article explaining that 'getting' something has an entirely different meaning whatsoever.
In my opinion comments should explain why you do something (if it is not obvious). The code itself should tell how it is done.
If you cannot understand what the code does, the code might be bad.
If you understand the code but don't understand why a specific action is executed, you are missing a comment.
So instead of adding a comment like // read user input you should name your methods and variables in a useful way:
...
String userInput = getUserInput();
...
No comment needed to understand this.
Don't stress too much about the exact language of the comments. You just want them to be clear so that whom ever comes behind you to maintain the code will understand what is going on. Don't worry about syntax for comments, it really isn't that important.
You could say:
//get user input
//read user input
//take user input
Honestly, it is one of the least important things to worry about. Just make sure that people know what you are doing. I'd focus on making the code itself clean and well-formatted, not the comments. It's important to have comments, as most programmers don't take the time to do it, but it isn't the most important thing.
It is more important to watch your verbiage when naming methods/classes/functions/variables. Not the comments.
:)
I thought of writing a piece of software which does Alpha Compositing. I didn't wanted ready made code off from internet so I tried to find research papers and other sources to understand the mathematical algorithms, and initiated to implement.
But, I got lost very quickly. So my question is,
How should I approach these papers to extract the necessary details from it in order to write algorithm based on it. Any specific set of steps which works well?
Desired answer :
Read ...
Extract ...
Understand ...
Implement ...
Note: This question is not limited to only Alpha Compositing, so more generalised approach will be helpful. I have tagged Java and C++, because thats my desired language to implement the image processing.
What I have done so far?
This is not a homework question but it is of course better to say what I know. I have read wiki of Alpha compositing, and few closely related Image compositing research papers. But, I stuck at the next step to take in order to go from understanding to implementation.
Wikipedia
Technical Memo, Image compositing
I'd recommend reading articles with complex formulas with a pencil and paper. Work through the math involved until you have a good grasp on it. Then, you'll be ready to code.
Start with identifying the steps needed to perform your algorithm on some image data. Include all of the steps from loading the image itself into memory all the way through the complex calculations that you may need to perform. Then structure that list into pseudocode. Once you have that, it should be rather easy to code up.
Write pseudocode. Ideally, the authors of the research papers would have done this, but often they don't. Write pseudocode for some simple language like Matlab or possibly Python, and hack away at writing a working implementation based on the psuedocode.
If you understand some parts of the algorithm but not others, then implement your pseudocode into real code for the parts you understand, and leaving comments for the places you don't.
The section from The Pragmatic Programmer on "Tracer Bullets" basically describes this idea. You want to quickly hack together something that takes your data into some form of an output, and then iterate on the body of the code to get it to slowly resemble the algorithm you're trying to produce.
My answer is necessarily somewhat vague. There's no magic bullet for something like this.
Have you implemented any image processing algorithms? Maybe start with something a little simpler, like desaturation/color intensification, reversal (side to side and upside down), rotating, scaling, and compositing images through a mask.
Once you have those figured out, you will be in a very good position to do an alpha composite.
I agree that academic papers seem to go out of their way to make implementation details muddy and uncertain. I find that large amounts of simplification to what is written is needed to begin to perform a practical implementation. In their haste to be general, writers excessively parameterize every aspect. To build useful, reliable software, it is necessary to start with something simple which actually works so that it can be a framework to add features. To do that, it is necessary to throw away 80–90 percent of the academic generality. Often much can be done with a raft of symbolic constants, but abandoning generality (say for four and five dimensional images) doesn't really lose anything in practice.
My suggestion is to first write the algorithm using Matlab to make sure that you understood all the steps and then try to implement using C++ or java.
To add to the good suggestions above, try to write your pseudocode in simple module (Object oriented style ) so has to have a deep understanding of each part of your code while not loosing the big picture. Writing everything in a procedural way is good a the beginning but as the code grow, it might get become hard to keep up will all you are trying to do.
This example cites one of the seminal works on the topic: Compositing Digital Images by Porter & Duff. The class java.awt.AlphaComposite implements the same rules.