22

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)?

yannis
  • 39,547
  • 40
  • 183
  • 216
bancer
  • 361
  • 2
  • 6
  • You are almost always coding against some kind of API. What exactly do you mean when you say "program without API" ? – driis Jan 12 '12 at 18:45
  • 2
    I think he's asking about *documentation*, specifically API references. –  Jan 12 '12 at 18:51
  • @driis: I ment Java API documentation (native Java classes). – bancer Jan 12 '12 at 19:03
  • 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
  • Has I work in a University, I see some professors not looking to have a lot of correction to do. So, some of them use shortcuts to trip the students and eventually avoid doing corrections since they failed early in the process – JF Dion Jan 12 '12 at 20:12
  • Apparently it is at those folks. Sounds like they wanted an idea of your current skillset. –  Jan 12 '12 at 20:25
  • 28
    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. – Dawood ibn Kareem 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
  • 2
    You still have it easy. In our university exam we have to write a Java program with **pen and paper**. – siamii Jan 13 '12 at 00:48
  • That's interesting. At my university all our tests are open book/open notes, and that's the way I think it should be! – Casey Patton Jan 13 '12 at 22:53
  • It's absolutely useless to demand from a programmer to memorize by heart an API. That's why clever IDEs and auto-completion/documentation techniques exist. Of course the more you use a specific API the more productive you become because lookups are eliminated. – sakisk Mar 31 '12 at 11:16
  • 1
    possible duplicate of [Would a cut and paste coder ever get past a job interview?](http://programmers.stackexchange.com/questions/63504/would-a-cut-and-paste-coder-ever-get-past-a-job-interview) – BЈовић May 03 '13 at 09:20
  • 1
    @Antonio2011aL: "My undergraduate studies were mostly in math and physics, but I remember having to memorize a lot of formula etc": You do not have to memorize those formulas. You have to understand how they work and what they are good for. After you have learnt how to use a formula, remembering the formula itself comes as a side effect. – Giorgio May 09 '13 at 09:01
  • I believe memorization for certification exams is a good point. Even if the user forgets 50% of it, the user still retains 50% and that's useful. Imagine, you are not good with knowing which classes are there, specifically their API's. How will you discuss technical solutions with your colleagues. There is a good probability you will say, "Hey, Java8 has support for transforming your image to a Unicorn when you call Transform.toUnicorn(), this will help us solve our problem where Unicorns don't exist". This way, you would also communicate better, and also you will be able to go....continued – We are Borg Sep 25 '15 at 14:08
  • Also, It's not possible to know all the API's out of the hat. If someone says that, I will surely give them a Thousand yard stare and march upon them with my newly created Unicorn. Concluding, it helps knowing the API's, classes and I believe this is what certifications, universites, exams, etc are trying to do, by nudging you in the right direction. – We are Borg Sep 25 '15 at 14:10

10 Answers10

40

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 how you solve a problem without looking at 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 a 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 not a coincidence: programmers are expected to learn on the job, and the API documentation for popular programming systems, including Java, is structured to help them learn quickly. To helps programmers complete their tasks without requiring prior familiarity with the API, the documentation often supplies short, self-contained examples, which illustrate the concept in a brief and concise way. This covers a wide range of tasks, including most problems that you may see at an examination.

Unfortunately, this works directly against your professor's goal of measuring your knowledge of the subject, as opposed to measuring how smart you are. Hence, in a university settings it is not unreasonable to ask you to code without looking at the documentation.

Sergey Kalinichenko
  • 17,393
  • 4
  • 57
  • 73
  • 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! – Sergey Kalinichenko 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
21

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.

Community
  • 1
Mike Nakis
  • 32,003
  • 7
  • 76
  • 111
  • +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 09:59
9

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.

Paul
  • 730
  • 3
  • 13
9

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.

gnat
  • 21,442
  • 29
  • 112
  • 288
  • 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 08: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 02:58
3

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.

Rei Miyasaka
  • 4,541
  • 1
  • 32
  • 36
2

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.

Matt
  • 515
  • 3
  • 5
2

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.

Goran Jovic
  • 2,748
  • 23
  • 28
  • 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
  • @ReiMiyasaka: Replace 'loop' with any functional operation you consider elementary enough, say list comprehension, and my point is the same. Students should know elementary things at any time, especially during exam. (I am not implying that loops and comprehensions are equivalent, just that both are usually considered elementary in their respective paradigms) – Goran Jovic Jan 12 '12 at 23:09
  • @Goran That's the thing though, I don't remember the exact syntax for list comprehensions in Haskell either. I can easily figure it out from the usage and the general *look* of `[ x | x..x ]`. I've taken a course on it, and fortunately my instructor was sensible enough not to test us on anything syntax-related on the exams. He gave us a list of the higher-order functions, and as far as I can tell, never was very particular about correct syntax. As a result, while I don't use Haskell for my daily work, I have no trouble understanding it when I read it in academic papers -- and it's great. – Rei Miyasaka Jan 13 '12 at 02:44
2

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.

Jarrod Nettles
  • 6,125
  • 2
  • 41
  • 45
Stephanie
  • 21
  • 2
2

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.

Coder
  • 6,958
  • 5
  • 37
  • 49
1

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.

Coyote21
  • 437
  • 2
  • 4