Date: 2020-03-19
The colleague is incorrect. Javadoc comments are used to document the intended behaviour of methods and classes. Without a record of this intended behaviour, it will be difficult for other developers to make use of my code. They will also be unable to write tests for it, since if there is no description of the intended behaviour, how can they possibly know what to test for? It is not relevant that the code is only being used internally – if anyone in the company is going to make use of the code or write tests for it, then documentation of the intended behaviour is needed.
Whilst it might be possible to specify the intended behaviour of methods and classes in an external document, this makes it easy for that document to get out of sync with the code, so Javadoc is a preferable way of doing this.
The answer correctly identifies the purpose of Javadoc comments (and API documentation in general). The purpose of Javadoc comments is discussed in lecture 2 (especially slides 3–17; slides 36 onward highlight that we do not use Javadoc to document the implementation of methods or classes – only the interface).
The answer does not introduce irrelevant or incorrect information – for instance, stating that the purpose of Javadoc comments is to explain the implementation of the method, or to remind ourselves how it works.
The answer mentions that it is possible to document an API externally (rather than using Javadoc), but gives reasons why this is not a good idea.
I think my colleague is incorrect. Comments are very useful for understanding code. They will also help me if I need to understand my own code later. They will make writing tests easier and faster. I can record preconditions and postconditions for the code, and these will make it much easier for the testing team later. It is good practice for all developers to document their code.
This answer fails to identify that the scenario given is not about commenting in general, but about Javadoc comments. As a result, it includes information which is incorrect or irrelevant when considering why we should document the API for our code.
It also suggests that writing tests will be “easier and faster” – without addressing the fact that without some description of code’s intended behaviour, it is not possible to test code at all. We said that testing is an attempt to identify failures; and failures are behaviour which doesn’t satisfy specifications. So if there are no specifications, there can be no failures, and thus, no tests.
It also appeals to the idea that it is “good practice” for developers to document their code. This is a poor justification – it really just means that some practice is “commonly used” and “good”, which is an example of begging the question; if you are asked to explain why documenting intended behaviour is good, you can’t justify it by saying that “is is commonly done and is good”.
Unit testing is defined as testing of a small, independent unit of code, such as a single method or class.
We need to be able to maintain our code properly, so we should write comments for all our classes and methods. We need to know what classes and methods are in the code, in case we later need to make changes. Otherwise they will need to ask us what the methods do.
Javadoc is the best tool for this.
This answer has some similar issues to the “satisfactory” answer, but also gives definitions of concepts that are not at all relevant to the scenario (in this case, “unit testing”).
It doesn’t explicitly address the purpose of Javadoc comments at all, except to indirectly suggest that if the code is being changed, the Javadoc comments will record the purpose of the classes or methods.
Additionally, it never actually provides a clear “yes” or “no” answer to the question.
In general, this is not good practice. It would be better to avoid duplicated code, and instead factor the common code out (for instance, into a separate method). Otherwise, if requirements for connecting to the database later change, the duplicated code increases the chance that errors will be made (e.g., updating some instances of the duplicated code, and not others).
Since we are using JUnit, a plausible way to factor out the code would be to put it into a “setUp” method in the relevant test classes – JUnit calls this method before each test that is run.
The answer succinctly explains why this is not good practice: it increases the chance for error, later. It does not mention any irrelevant facts or topics.
Unit tests are supposed to be fast, so we should avoid duplicated code – additionally, it violates the “DRY” principle (“Do not Repeat Yourself”). So, this is not good practice, and will cause problems later if requirements for connecting to the database change – we may forget to update one.
We should use a “setUp” method, and connect once to the database, and re-use the connection. Test fixtures are defined as state required for a test – they constitue prefix values supplied for a test.
This answer does still hit on the reason duplicated code is usually poor practice: it can result in errors when requirements change. However, it does not state it very clearly, and makes a number of irrelevant and/or incorrect statements.
Firstly, it assumes that the tests here are unit tests; but this is never stated in the scenario, and need not be the case. We saw in the lectures that JUnit can be used for integration and system tests as well. Due to this incorrect assumption, the answer mentions factors that may not be relevant (e.g. a requirement for tests to be very fast). It also supplies a definition of “test fixture” which is not especially relevant or useful.
Saying that something violates the “DRY” principle is not an especially good justification, since it simply begs the question: a reader might ask, Why should you not repeat yourself? A better justification would be to explain what problems duplicated code leads to.
Tests should be independent of one another. We should use a “setUp” method here, and connect to the database only once, to improve speed. However, repeating the code makes the tests more readable. Testing is defined as an attempt to show our code is correct.
This does not manage to identify any relevant facts nor topics, nor state an answer to the question, nor justify a recommended approach. Additionally, it contains irrelevant definitions (of “testing”, in this case), which in any case are wrong.
It asserts that tests should be independent of each other, which is something we have only said is true for unit tests (in lecture 2). (In fact, it is probably good practice for most tests, but this answer does not provide any good grounds for thinking so.) An assertion is not a justification; a better answer would at least explain why tests should be independent.
The answer also irrelevantly states that repeated code makes the tests more readable. Which might be true – if you’re looking at an individual test, you can read the code without having to look at a separate method elsewhere – but has very low relevance, since the advantages of readability are strongly outweighed by the problems of maintenance.