Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I barely passed my Java programming exam today. I had to answer some general questions about threading which I did well and to write a little threaded program which was worse. I had to connect my laptop to the projector screen and write the program right away. My first attempt was to use anonymous classes but I forgot the exact syntax. Maybe because of some excitement or maybe because last two weeks I was coding mostly in php. Then I asked is it allowed to use the API documentation. The answer was "NO". So I decided to go another way around and I implemented Runnable. The program was doing what was requested at the end. Of course the examiners noticed my first fail and that affected my score greatly. I was amazed that it was not allowed to use the API documentation.

So, my question is: Is it really important to be able to code flawlessly without API documentation? Should I develop this skill? Is it really important in the real world and in the work environment? While on programming courses I focused on learning patterns, developing skills to write good design applications, skills to use API and find the necessary information fast. I was not trying to learn how to program without API documentation. Is it must-have during job interviews (coding without API documentation)?

share|improve this question
2  
I think he's asking about documentation, specifically API references. –  delnan Jan 12 '12 at 18:51
3  
@bancer - You not being able to use native java classes makes no sense. It sounds like you were not prepared for the exam. –  Ramhound Jan 12 '12 at 19:36
25  
In the real world you will always have access to the documentation. I have a terrible memory and try to focus on the general logic of my application and avoid filling my mind with pointless memorization of things that can easily be looked up. Unfortunately the academic world (and the world of certifications) is somewhat different and there is often an emphasis on pointless memorization. My undergraduate studies were mostly in math and physics, but I remember having to memorize a lot of formula etc. What a waste of time. –  Antonio2011a Jan 12 '12 at 21:10
11  
@Antonio2011a - Knowing the API of the language that you're using is NOT "pointless memorisation". The better you know the API, the better you'll be able to program, because you'll choose appropriate classes and methods for your solution. You can't choose them if you don't know they exist. Of course, nobody knows the entire Java API; it's too big. But it's always good to know as much of it as you can manage. –  David Wallace Jan 12 '12 at 21:24
9  
@DavidWallace Maybe I wasn't clear. Of course I'm not saying that you don't need to be familiar with the API !! Just that you don't need to memorize the exact names of classes, methods, order of parameters, and other such mind numbing details ! All you really need to know is that it exists and how it is useful, then you can look up the details while coding. Like I said before my memory is terrible, and honestly I could have used a class an hour ago, and if you gave me a blank piece of paper I wouldn't be able to remember the exact details. –  Antonio2011a Jan 12 '12 at 23:45
show 9 more comments

11 Answers

up vote 38 down vote accepted

In Real Life™, I would rate this skill as a "nice to have", but not at all required. In a university setting it is different, however.

An ability to code without documentation can be used as an indirect indication of student's familiarity with the subject. In a sense, seeing you code something without touching the documentation tells the professor that you have practiced using the API before -- by doing your homework and other assignments, or perhaps even by programming for fun on your own. A smart person with cursory understanding of the API in question should be able to figure out almost any Java API on her own by looking at the documentation. This is no coincidence: programmers are often expected to learn on the job, and the API documentation for popular programming systems, including Java, is structured to help programmers learn quickly. Documentation often supplies short, self-contained examples, illustrating the concept in a brief and concise way.

This works directly against professor's goal of measuring your knowledge of the subject (as opposed to measuring how smart you are). Hence it is not unreasonable to ask you code without looking at the documentation.

NOTE: I edited this answer in response to an edit of the question.

share|improve this answer
2  
From my reading, the examiners were looking at his ability to memorize the API documentation. He knew what to do, just didn't remember the syntax. –  Paul Jan 12 '12 at 19:30
    
@Paul I read the edits, and changed my answer. I thought the OP was asking something entirely different. Thanks! –  dasblinkenlight Jan 12 '12 at 20:14
2  
+1 for identifying the real issue here. If it were a job interview, the interviewer would be more interested in how you go about solving a problem, and you'd probably be allowed to just write your best approximation of the syntax on the whiteboard. When you've spent the past three months learning specific material, and you are being tested on that specific material, it's reasonable not to have an "open-Internet" policy. –  StriplingWarrior Jan 12 '12 at 22:35
    
@Paul: you are right –  bancer Jan 12 '12 at 22:39
add comment

No. I would be dead without the ability to look up from the API documentation. The only time I don't have it is when I'm trying to debug something where I can't get access to the documentation. Then I "reverse engineer" the api and cut-n-paste pieces as needed.

It's important to have a good idea of what the API is about and which part is best to use, but knowing the method names, variable names... not really necessary.

share|improve this answer
add comment

Is it a really required skill to program without API documentation?

I wouldn't say that it is required but it is

very desirable skill

imNSho.

I spent recent few months coding in close collaboration with the guy who knows API noticeably better than me. He is just so much more productive - simply because he can skip API docs checks that distract me.


Here, I am talking about fluency. About being not just capable of something but fluent.

Do you know what it is to be fluent? It's when for someone looking at you it appears as if you code as you type...

  • ...As if the right code simply flows from your fingers to the screen. As if you don't check the API docs, tutorials and manuals. Actually, you do check them all, but that's invisible because it's all in your head. You've got all the knowledge you need right there in your brain - charged, loaded and ready to use.

...That's fluent knowledge. It's when it takes you a minute to do what takes newbie an hour. It's worth the effort, really. It smells like victory.

If you master fluency in some API and if you properly memorize how does it feel like, this memory will further guide you through in how to become most productive working with any other API.

share|improve this answer
    
I don't think his question is whether or not you should eventually know the documentation, but whether or not you should memorize documentation as if for exams. –  Rei Miyasaka Jan 12 '12 at 19:47
    
@ReiMiyasaka well if you skip verbose exam-whining you may notice this: "So, my question is: Is it really important to be able to code flawlessly without API documentation? Should I develop this skill? Is it really important in the real world and in the work environment?". I focused on this part of the question because, you see, my recent experience made me feel quite uncomfortable about the idea that it can just fly by with elementary answer it is not required. Fair enough? –  gnat Jan 13 '12 at 8:00
2  
+1 for covering the cost of context switching to the reference docs. Having to look up every step slows things to a crawl. –  Wyatt Barnett Jan 14 '12 at 2:58
add comment

In work I've never had a situation where I had no access to documentation. On the other hand, having the reading comprehension and general understanding to be able to interpret poorly-written documentation comes in useful all the time.

You should eventually get to know the patterns and structure of your APIs, but knowing exactly where everything is is not particularly useful.

At SFU Computing Science, closed-book exams constitute between 70% and 100% of our grades. The theory is that exams test your understanding of the course material and your adaptability. In reality, all it really tests is your nerves, your sleep quality/duration, your wit, and your rote memorization techniques -- none of which is necessary either academically or for a typical job in the software industry.

share|improve this answer
add comment

To all but your last question: Encyclopaedic knowledge of any API documentation is not important. You will obviously program faster if you know every detail of every method of every class, but that's not a reasonable expectation.

To your last question: You may be expected to know the specifics of some classes without the API documentation. If you know before walking in to the interview that you will be tested, or if the job is very focused (i.e.: you will be doing threading all day), then you could reasonably expect to need to know the related classes in detail.


Addendum: You should clarify well before any exam with your professor/instructor exactly what materials will be provided and what materials you may bring yourself. Assume that anything they have not explicitly agreed to is not allowed. I've had courses where I could only bring the basics for writing, where I could bring any books I wished, and where I could bring exactly one double-sided sheet with anything I wanted on it. Exams are usually structured around what materials are allowed.

share|improve this answer
add comment

API docs != language syntax.

I can understand when someone doesn't know the exact names of various Java classes and their methods. I don't know them and I code in Java every day. I'd be lost without either the docs or the almighty IDE auto-completion - especially when it comes to Java standard API which is well known for its verbosity in variable/class/method names.

However, as you said yourself, it isn't anything which is usually found in docs that you could't remember. It is the syntax for inner classes - this is a feature of language itself not something to be memorized from the docs.

As much as I think that students should (in many cases) be allowed to use the docs for standard APIs, I do think that anyone who wants to pass a programming exam should know the language syntax. And I don't mean some freaky edge cases that only language designers know about, just the standard ones - like the one in your example.

share|improve this answer
2  
I don't think it's worth memorizing syntax either. Features and patterns and gotchas, yes, but syntax, no. I work with too many languages for it to be meaningful, and I think that's becoming true of most developers as well. –  Rei Miyasaka Jan 12 '12 at 20:19
    
@ReiMiyasaka: I don't think you should memorize entire language specs, but you should know the basic syntax at any moment. Do you look up in the docs how to write a loop in any of your languages? Or do you just code it? –  Goran Jovic Jan 12 '12 at 20:25
    
In truth I work with quite a number of languages, and I often forget the exact syntax even for basic things !! So I find myself always needing to refer to the docs. –  Antonio2011a Jan 12 '12 at 21:06
    
@Antonio2011a: I admit that I do that myself, especially when I use less common languages. But for many students the language being learned is the first programming language ever. If a student didn't even learn the syntax then it doesn't say anything good on how he/she prepared for the exam. –  Goran Jovic Jan 12 '12 at 21:20
    
@Goran Actually I don't necessarily, for two reasons: 1. background compiling tells me when I get the syntax wrong, and 2. loops are secondary (almost non-existent) in languages like Haskell and ML. Languages are more diverse than you might think. Even though I spend most of my time coding in F# and only vaguely remember Haskell, I can still understand Haskell code just fine, remembering to take note of the semantic differences. On the other hand I agree that learning a first language inside-out is extremely important and way-too-often neglected. –  Rei Miyasaka Jan 12 '12 at 21:52
show 2 more comments

There was a guy once who had a little bug in his code, so he took it to StackOverflow and asked for help. StackOverflow: Java (generating numbers with no repeats ). I looked at his code and I pointed out to him that his HashSet was perpetually being filled with values but it was never cleared. So, he asked me: "how do you clear it?" I have to admit that I am not particularly proud of the answer I gave.

You absolutely need to know the basic stuff that you use every day. You need to know them all, and you need to know them well. But only the basic stuff.

For everything else, the important thing is to know that there is something out there that does what you want. Precisely which class you need to use, precisely which method you need to call, and precisely what parameters you need to pass to it, is something that you do not need to keep precious neurons of your brain occupied with. That's what documentation is for, and that's why IDEs with autocomplete were invented. And if push comes to shove, there is always StackOverflow and the greater interwebz out there.

Asking programmers to know by heart APIs is akin to asking lawyers to know by heart the legal code and all precedents. It is pointless. An exercise in futility.

share|improve this answer
    
+1: It's incredibly difficult to learn the whole API of a large library such as the Java one, simply because of its sheer size. Knowing what general capabilities are provided by packages is easier though (e.g., javax.imageio provides advanced image handling, not that I've ever used it) and some core facilities should be learned. In particular, java.lang and java.util are going to be used in virtually every Java program ever. –  Donal Fellows Jan 13 '12 at 9:59
add comment

if you start working on some project for some not short time using an api sooner or later you'll learn that api very well. i believe this is totally unnecessary skill since i don't know anyone who never ever takes a look at any documentation (msdn, man pages, etc...)

however universities are an entirely different universe, so don't be surprised if you fail beacuse you don't know the typedef name of 10.th parameter of CreateWindowEx, for example.

share|improve this answer
    
Not consistent with my experience of universities. If anything, they tented to be obsessed with theory and lacked attention to details. Or has the level dropped to the one of vocational schools? –  AProgrammer Jan 13 '12 at 8:04
    
i am not talking about one university, and this is just an example of what you may see somewhere in the world in some university. as you know, they are not all the same –  Hayri Uğur Koltuk Jan 13 '12 at 17:53
2  
Universities have always had some degree of memorize-and-regurgitate. I'd have aced calculus if I'd had a CRC book available instead of having to memorize integral tables. –  Blrfl Jan 24 '12 at 18:04
add comment

I would say, no it isn't required, it is physically impossible for the human brain to memorise so much information, but you still need to know the basics or the most used things, since there aren't a lot of those to memorise. Otherwise, it's impossible to memorise everything that there is on java.

Also it is unfair for a teacher to want his students to know everything, or to use that to know if they program with a language, besides the exercises or projects he assigns to you. For me it's like wanting to know what you do when your not on school or doing related work.

EDIT: Obviously, what the teacher asks to you depends on him, some teachers value theory more while others value practise and don't care if you don't understand everything.

share|improve this answer
add comment

In Eclipse you can write obj. and press ctrl+space and it will try to auto-complete by giving you all the method options for the given object. If that fails me for some reason the Java API has the rest of the answers. I'd be hard pressed to think of a day when I didn't Google how to do something.

School is a completely different story though.

share|improve this answer
add comment

IMHO, academia usually stinks at producing good software engineers. Only people who code for fun after the lessons have a chance to achieve something in real world projects.

Then again, academia is not about producing developers, the whole world is about how to solve abstract problems and do the research. It's very far from practical application most of the time. And researchers are not necessarily a good coders.

And learning API by heart stinks. There is autocomplete/google/msdn/javadocs to look up all the nooks and crannies, why would anyone want to keep all that in their brain at all times? Most common functions you'll learn in few weeks/months, everything else can be looked up in a matter of seconds if you know the syntax, structure and general ideas.

Then again, some people still code in text editors and remember function names by heart, that's not necessarily wrong, but if they're fanatic about it, you got your professor.

Moreover, even if you know function names and parameters by heart, it's still a good idea to verify them in the latest API doc. strtok was fine in single threaded scenario 10 years ago, it's not fine nowadays. If you just learn the names and parameters you'll never know that the functionality might be deprecated or better alternatives invented.

Languages change, so you need to change with them, remembering one true way is not good for that.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.