Is there a practical or historical reasoning behind languages allowing the most egregious naming convention taboos? The two most obvious examples are uppercase function names and lowercase class names, which I often see violated in stackoverflow newbie questions.
There is no style-justification that I know of where you can do these things, so why are they even allowed to compile? At the moment, my theories are
It was not such a taboo when the language was built,
It would make some important edge cases impossible, or
It's not the language's job to enforce good style.
I can find nothing on this topic (some links are below).
There are some conventions, such as underscores beginning variable names, or Hungarian notation (the latter of which I have been personally disabused of in comments) that are not overwhelmingly accepted, but are less divisive.
I'm asking this as a Java programmer, but would also be interested in answers form other language's.
Some links:
http://en.wikipedia.org/wiki/Naming_convention_(programming)#Java
http://docs.oracle.com/javase/tutorial/java/javaOO/methods.html
http://en.wikibooks.org/wiki/Java_Programming/History
How important are naming conventions for getters in Java?
Coding style is like writing style. If you write in a style that is diFFicult TO READ And does not read very well your mINd hAs GReat diFFICULTies actUally understanding what you are reading.
If, however, like in normal reading text - it is laid out in a form that matches well with what your mind expects then it is clear and easy to understand.
On the other hand, if the language actually FORCED you to write everything using EXACTLY the the right syntax then not only would it make coding slow and awkward but it would restrict your expressiveness.
Many years ago I came across a language that allowed you to add strange symbols to variable names. Users were allowed to do thing like:
var a=b = a = b;
var c<d = c > d;
if ( a=b & c<d ) ...
i.e. a=b was a perfectly acceptable variable name, so was c<d. As I am sure you would agree, this led to many mistakes of interpretation. Even if a new language allowed that I would not use it. Coding standards are for consistency and helping the human mind understand, syntax is for helping the computer mind understand.
Depending on the language designer's intent some languages are more opinionated than others when it comes to implementation and how the designers think things should be done.
The easiest example I can think of right now is Go, which has unit testing and code formatting built in. The designers are of the opinion that things should be done a certain way and they provide you the tools to do it.
Other languages do nothing of the sort like Scala where the language designers were very unopinionated in their implementation and supply you the tools to accomplish any given task in 10 different ways.
This isn't to say that some languages are built under tyrannical rule and others are extremely loose with their requirements. Its merely a choice made by the language designers which we end up having to live with.
This question already has answers here:
Closed 10 years ago.
Possible Duplicate:
Advantages and Disadvantages of using System.out.printf();
In a discussion in an online forum, I was told that using printf method (like in System.out.printf()) was a bad practice and that I should use println instead, although the user couldn't give a clear explanation for that, it was something that "he was told". Is this true?
If you need the formatting capabilities of printf, then there's no question as println isn't an acceptable alternative.
If on the other hand you're just outputting a normal string, e.g.:
System.out.printf("All work completed.\n");
then it would be more canonical to use println for this. In terms of program correctness it doesn't really matter - printf will probably be marginally more expensive to run but in reality this is not going to be relevant.
However, I did see some example code that used printf for simple output and I'll admit I found it confusing. So I'd stick to println for that reason alone, that it will make your code more familiar and easier to understand for other developers.
(ETA: Even reviewing my own post now, I instinctively feel that the code sample is wrong and want to correct it to println. So my earlier opinion definitely still holds.)
No it is not true.
The only possible rationale I can think of is that printf with a literal \n and/or \n in the format string is going to produce platform specific line breaks ... which is a portability issue. But the simple solution is to use %n in the format string.
Of course, using printf when no arguments need to be substituted into the format string is less than optimal. I wouldn't say that this makes it Bad Practice though.
printf can do things which println can't, so saying that you should always use println rather than printf obviously doesn't make sense.
For people who don't know the formatting specifiers used in printf control strings, they can be hard to read -- that might be the reason the person you talked to advised you not to use printf.
Some more general advice for next time: Remember there are a lot of people who will happily give you advice despite not knowing what they're talking about, and even among those who do know what they're talking about, there are as many opinions about programming as there are programmers. So you should never take anything as gospel just because someone told you or because you read it in a book. Always try to understand the reasons for the advice, and remember that there are exceptions to every rule. Understand that virtually every decision you make when designing or implementing a program has both pros and cons, so usually there is no one option which is unconditionally "right"; you have to use your experience and judgement to determine what is the "right" way to do things in your current situation, even if it might be "wrong" in most other cases.
Using either one is "bad" practice if you are doing it for debug logging.
If that is the case using a proper logging framework is the "best" practice. Java has plenty to pick from.
I need a library/function/method to perform a Fisher's exact test in Java, and provide the right, left and two-tailed probabilities.
Simple Googling shows a solution within the packages of Tassel, but the method inside simply applies the test steps with no optimization, and therefore it's extremely slow. Moreover, it uses int types everywhere and it's not really efficient for big contingency tables.
If you know any already written solution, help me :-)
See if this helps: http://www.users.zetnet.co.uk/hopwood/tools/StatTests.java
The formula is quite simple. There's a very simple (two-tailed) implementation here: http://javanus.com/blogs/?p=51 (see the comment by Discretoboy for a much cleaner implementation)
You can also take a look at the test implementation in Java Statistical Classes.
I use http://wordhoard.northwestern.edu/userman/javadoc/edu/northwestern/at/utils/math/statistics/FishersExactTest.html
A (very) brief test showed it to be similar in speed to the Java Statistical Classes (jsc) test mentioned above but it had the additional advantage of not giving me an illegal argument exception when my table included zero, which I believe is a legitimate case.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
Much of my programming background is in Java, and I'm still doing most of my programming in Java. However, I'm starting to learn Python for some side projects at work, and I'd like to learn it as independent of my Java background as possible - i.e. I don't want to just program Java in Python. What are some things I should look out for?
A quick example - when looking through the Python tutorial, I came across the fact that defaulted mutable parameters of a function (such as a list) are persisted (remembered from call to call). This was counter-intuitive to me as a Java programmer and hard to get my head around. (See here and here if you don't understand the example.)
Someone also provided me with this list, which I found helpful, but short. Anyone have any other examples of how a Java programmer might tend to misuse Python...? Or things a Java programmer would falsely assume or have trouble understanding?
Edit: Ok, a brief overview of the reasons addressed by the article I linked to to prevent duplicates in the answers (as suggested by Bill the Lizard). (Please let me know if I make a mistake in phrasing, I've only just started with Python so I may not understand all the concepts fully. And a disclaimer - these are going to be very brief, so if you don't understand what it's getting at check out the link.)
A static method in Java does not translate to a Python classmethod
A switch statement in Java translates to a hash table in Python
Don't use XML
Getters and setters are evil (hey, I'm just quoting :) )
Code duplication is often a necessary evil in Java (e.g. method overloading), but not in Python
(And if you find this question at all interesting, check out the link anyway. :) It's quite good.)
Don't put everything into classes. Python's built-in list and dictionaries will take you far.
Don't worry about keeping one class per module. Divide modules by purpose, not by class.
Use inheritance for behavior, not interfaces. Don't create an "Animal" class for "Dog" and "Cat" to inherit from, just so you can have a generic "make_sound" method.
Just do this:
class Dog(object):
def make_sound(self):
return "woof!"
class Cat(object):
def make_sound(self):
return "meow!"
class LolCat(object):
def make_sound(self):
return "i can has cheezburger?"
The referenced article has some good advice that can easily be misquoted and misunderstood. And some bad advice.
Leave Java behind. Start fresh. "do not trust your [Java-based] instincts". Saying things are "counter-intuitive" is a bad habit in any programming discipline. When learning a new language, start fresh, and drop your habits. Your intuition must be wrong.
Languages are different. Otherwise, they'd be the same language with different syntax, and there'd be simple translators. Because there are not simple translators, there's no simple mapping. That means that intuition is unhelpful and dangerous.
"A static method in Java does not translate to a Python classmethod." This kind of thing is really limited and unhelpful. Python has a staticmethod decorator. It also has a classmethod decorator, for which Java has no equivalent.
This point, BTW, also included the much more helpful advice on not needlessly wrapping everything in a class. "The idiomatic translation of a Java static method is usually a module-level function".
The Java switch statement in Java can be implemented several ways. First, and foremost, it's usually an if elif elif elif construct. The article is unhelpful in this respect. If you're absolutely sure this is too slow (and can prove it) you can use a Python dictionary as a slightly faster mapping from value to block of code. Blindly translating switch to dictionary (without thinking) is really bad advice.
Don't use XML. Doesn't make sense when taken out of context. In context it means don't rely on XML to add flexibility. Java relies on describing stuff in XML; WSDL files, for example, repeat information that's obvious from inspecting the code. Python relies on introspection instead of restating everything in XML.
But Python has excellent XML processing libraries. Several.
Getters and setters are not required in Python they way they're required in Java. First, you have better introspection in Python, so you don't need getters and setters to help make dynamic bean objects. (For that, you use collections.namedtuple).
However, you have the property decorator which will bundle getters (and setters) into an attribute-like construct. The point is that Python prefers naked attributes; when necessary, we can bundle getters and setters to appear as if there's a simple attribute.
Also, Python has descriptor classes if properties aren't sophisticated enough.
Code duplication is often a necessary evil in Java (e.g. method overloading), but not in Python. Correct. Python uses optional arguments instead of method overloading.
The bullet point went on to talk about closure; that isn't as helpful as the simple advice to use default argument values wisely.
One thing you might be used to in Java that you won't find in Python is strict privacy. This is not so much something to look out for as it is something not to look for (I am embarrassed by how long I searched for a Python equivalent to 'private' when I started out!). Instead, Python has much more transparency and easier introspection than Java. This falls under what is sometimes described as the "we're all consenting adults here" philosophy. There are a few conventions and language mechanisms to help prevent accidental use of "unpublic" methods and so forth, but the whole mindset of information hiding is virtually absent in Python.
The biggest one I can think of is not understanding or not fully utilizing duck typing. In Java you're required to specify very explicit and detailed type information upfront. In Python typing is both dynamic and largely implicit. The philosophy is that you should be thinking about your program at a higher level than nominal types. For example, in Python, you don't use inheritance to model substitutability. Substitutability comes by default as a result of duck typing. Inheritance is only a programmer convenience for reusing implementation.
Similarly, the Pythonic idiom is "beg forgiveness, don't ask permission". Explicit typing is considered evil. Don't check whether a parameter is a certain type upfront. Just try to do whatever you need to do with the parameter. If it doesn't conform to the proper interface, it will throw a very clear exception and you will be able to find the problem very quickly. If someone passes a parameter of a type that was nominally unexpected but has the same interface as what you expected, then you've gained flexibility for free.
The most important thing, from a Java POV, is that it's perfectly ok to not make classes for everything. There are many situations where a procedural approach is simpler and shorter.
The next most important thing is that you will have to get over the notion that the type of an object controls what it may do; rather, the code controls what objects must be able to support at runtime (this is by virtue of duck-typing).
Oh, and use native lists and dicts (not customized descendants) as far as possible.
The way exceptions are treated in Python is different from
how they are treated in Java. While in Java the advice
is to use exceptions only for exceptional conditions this is not
so with Python.
In Python things like Iterator makes use of exception mechanism to signal that there are no more items.But such a design is not considered as good practice in Java.
As Alex Martelli puts in his book Python in a Nutshell
the exception mechanism with other languages (and applicable to Java)
is LBYL (Look Before You Leap) :
is to check in advance, before attempting an operation, for all circumstances that might make the operation invalid.
Where as with Python the approach is EAFP (it's easier to Ask for forgiveness than permission)
A corrollary to "Don't use classes for everything": callbacks.
The Java way for doing callbacks relies on passing objects that implement the callback interface (for example ActionListener with its actionPerformed() method). Nothing of this sort is necessary in Python, you can directly pass methods or even locally defined functions:
def handler():
print("click!")
button.onclick(handler)
Or even lambdas:
button.onclick(lambda: print("click!\n"))
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
Should I be writing Doc Comments for all of my java methods?
#Claudiu
When I write code that others will use - Yes. Every method that somebody else can use (any public method) should have a javadoc at least stating its obvious purpose.
#Daniel Spiewak
I thoroughly document every public method in every API class. Classes which have public members but which are not intended for external consumption are prominently marked in the class javadoc. I also document every protected method in every API class, though to a lesser extent. This goes on the idea that any developer who is extending an API class will already have a fair concept of what's going on.
Finally, I will occasionally document private and package private methods for my own benefit. Any method or field that I think needs some explanation in its usage will receive documentation, regardless of its visibility.
#Paul de Vrieze
For things, like trivial getters and setters, share the comment between then and describe the purpose of the property, not of the getter/setter
/**
* Get the current value of the foo property.
* The foo property controls the initial guess used by the bla algorithm in
* {#link #bla}
* #return The initial guess used by {#link #bla}
*/
int getFoo() {
return foo;
}
And yes, this is more work.
#VonC
When you break a huge complex method (because of high cyclomatic complexity reason) into:
one public method calling
several private methods which represent internal steps of the public one
, it is very useful to javadoc the private methods as well, even though that documentation will not be visible in the javadoc API files.
Still, it allows you to remember more easily the precise nature of the different steps of your complex algorithm.
And remember: limit values or boundary conditions should be part of your javadoc as well.
Plus, javadoc is way better than simple "//comment":
It is recognized by IDE and used to display a pop-up when you move your cursor on top of one of your - javadoc-ed - function. For instance, a constant - that is private static final variable -, should have a javadoc, especially when its value is not trivial. Case in point: regexp (its javadoc should includes the regexp in its non-escaped form, what is purpose is and a literal example matched by the regexp)
It can be parsed by external tools (like xdoclet)
#Domci
For me, if somebody will see it or not doesn't matter - it's not likely I'll know what some obscure piece of code I wrote does after a couple of months. [...]
In short, comment logic, not syntax, and do it only once, on a proper place.
#Miguel Ping
In order to comment something, you have to understand it first. When you trying to comment a function, you are actually thinking of what the method/function/class does, and this makes you be more specific and clear in your javadoc, which in turn makes you write more clear and concise code, which is good.
If the method is, obviously self evident, I might skip a javadoc comment.
Comments like
/** Does Foo */
void doFoo();
Really aren't that useful. (Overly simplistic example, but you get the idea)
I thoroughly document every public method in every API class. Classes which have public members but which are not intended for external consumption are prominently marked in the class javadoc. I also document every protected method in every API class, though to a lesser extent. This goes on the idea that any developer who is extending an API class will already have a fair concept of what's going on.
Finally, I will occasionally document private and package private methods for my own benefit. Any method or field that I think needs some explanation in its usage will receive documentation, regardless of its visibility.
All bases covered by others already; one additional note:
If you find yourself doing this:
/**
* This method currently launches the blaardh into the bleeyrg.
*/
void execute() { ... }
Consider changing it into this:
void launchBlaardhIntoBleeyrg() { ... }
This may seem a bit obvious, but in many cases the opportunity is easy to miss in your own code.
Finally keep in mind that the change is not always wanted; for instance the behaviour of the method may be expected to evolve over time (note the word "currently" in the JavaDoc).
For things, like trivial getters and setters, share the comment between then and describe the purpose of the property, not of the getter/setter.
/**
* Get foo
* #return The value of the foo property
*/
int getFoo() {
return foo;
}
Is not useful. Better do something like:
/**
* Get the current value of the foo property.
* The foo property controls the initial guess used by the bla algorithm in
* {#link #bla}
* #return The initial guess used by {#link #bla}
*/
int getFoo() {
return foo;
}
And yes, this is more work.
No, do not comment every method, variable, class, etc..
Here's a quote from "Clean Code: A Handbook of Agile Software Craftsmanship":
It is just plain silly to have a rule that says that every function must have a
javadoc, or every variable must have a comment. Comments like this just clutter
up the code, popagate lies, and lend to general confusion and disorganization.
A comment should exist if, and only if, it adds important information for the intended user of the method, variable, class, etc.. What constitutes "important" is worth consideration and could be a reminder to myself when/if I come back to this method/class/etc., a consequence/side effect of the method, motivation for why the thing even exists (in the case where some code is overcoming a shortcoming/bug of some library or system), important information about the performance or when it is appropriate to call, etc..
What is not a good comment but indicates the code itself should be rewritten/modified is a comment explaining the details of a complex and obscure method or function. Instead, prefer shorter clearer code.
When I write code for myself - NO. In this case, java doccing is a waste of my time.
When I write code that others will use - Yes. Every method that somebody else can use (any public method) should have a java doc at least stating its obvious purpose. For a good test - run the javadoc creation utility on your code (I forget the exact command line now). Browse through the webpage it generates. If you would be satisfied using a library with that level of documentation, you're golden. If not, Write more javadocs in your code.
There is another reason you should use javadocs. In order to comment something, you have to understand it first. When you trying to comment a function, you are actually thinking of what the method/function/class does, and this makes you be more specific and clear in your javadoc, which in turn makes you write more clear and concise code, which is good.
simply put: YES
The time you need to think about whether you should write a doc,
is better invested in writing a doc.
Writing a one-liner is better than spending time for not documenting the method at all in the end.
For me, if somebody will see it or not doesn't matter - it's not likely I'll know what some obscure piece of code I wrote does after a couple of months. There are a few guidelines:
APIs, framework classes, and internal reusable static methods should be commented thoroughly.
Logic in every complicated piece of code should be explained on two places - general logic in javadoc, and logic for each meaningful part of code in it's own comment.
Model properties should be commented if they're not obvious. For example, no point in commenting username and password, but type should at least have a comment which says what are possible values for type.
I don't document getters, setters, or anything done "by the book". If the team has a standard way of creating forms, adapters, controllers, facades... I don't document them, since there's no point if all adapters are the same and have a set of standard methods. Anyone familiar with framework will know what they're for - assuming that the framework philosophy and way of working with it is documented somewhere. In this cases, comments mean additional clutter and have no purpose. There are exceptions to this when class does something non-standard - then short comment is useful. Also, even if I'm creating form in a standard way, I like to divide parts of the form with short comments which divide the code into several parts, for example "billing address starts here".
In short, comment logic, not syntax, and do it only once, on a proper place.
Java doc should not be relied on, as it places a burden on developers making changes to maintain the java doc as well as the code.
Class names and function names should be explicit enough to explain what is going on.
If to explain what a class or method does makes its name too long to deal with, the class or method is not focused enough, and should be refactored into smaller units.
I feel there should at least be comments regarding the parameters accepted and return types in term of what they are.
One can skip the implementation details in case the function names describes it completely, for eg, sendEmail(..);
I make it a point to write javadoc comments whenever it is non-trivial, Writing javadoc comments when using an IDE like eclipse or netbeans isn't that troublesome. Besides, when you write a javadoc comment, you are being forced to think about not just what the method does, but what the method does exactly, and the assumptions you've made.
Another reason is that once you've understood your code and refactored it, the javadoc allows you to forget about what it does since you can always refer to it. I'm not advocating purposely forgetting what your methods do but it's just that I prefer to remember other things which are more important.
You should probably be documenting all of your methods really. Most important are public API methods (especially published API methods). Private methods are sometimes not documented, although I think they should be, just for clarity - same goes with protected methods. Your comments should be informative, and not just reiterate what the code does.
If a method is particularly complex, it is advised that you document it. Some people believe that code should be written clearly so that it doesn't require comments. However, this is not always possible, so comments should be used in these cases.
You can automate the generation of Javadoc comments for getters/setters from Eclipse via the code templates to save on the amount of documentation you have to write. another tip is to use the #{$inheritDoc} to prevent duplication of code comments between interfaces and implementation classes.
Javadoc can be really useful for libraries and reusable components. But let's be more practical. It is more important to have self explaining code than javadoc.
If you imagine a huge legacy project with Javadocs - would you rely on that? I do not think so... Someone has added Javadoc, then the implementation has changed, new feature was added (removed), so the Javadoc got obsolete.
As I mentioned I like to have javadocs for libraries, but for active projects I would prefer
small functions/classes with names which describe what they do
clear unit test cases which give explanation what the
function/classes do
at a previous company, we used to use the jalopy code formatter with eclipse. That would add javadoc to all the methods including private.
It made life difficult to document setters and getters. But what the heck. You have to do it -- you do it. That made me learn some macro functionality with XEmacs :-) You can automate it even further by writing a java parser and commenter like ANTLR creator did several years ago :-)
currently, I document all public methods and anything more than 10 lines.
You can run javadoc against code that does not have javadoc comments and it will produce fairly useable javadocs if you give thoughtful names to your methods and parameters.
I try to at the very least document every public and interface property and method, so that people calling into my code know what things are. I also try to comment as much as possible in line as well for maintenance sake. Even 'personal' projects I do on my own time just for myself, I try to javadoc just because I might shelf it for a year and come back to it later.
Assumed in all the answers so far is that the comments will be good comments. As we all know that is not always the case, sometimes they are even incorrect. If you have to read the code to determine its intent, boundaries, and expected error behavior then the comment is lacking. For example, is the method thread safe, can any arg be null, can it return null, etc. Comments should be part of any code reviews.
This may be even more important for private methods since a maintainer of the code base will have to contend with issues that an API user will not.
Perhaps IDEs should have a feature that allows the use of a documenting form so that the developer can check off various properties that are important and applicable for the current method.