#javadoc

Hey there, future coding wizards! Remember when we worked on methods, and things got a bit complicated? Wouldn’t it be nice to have notes to make sense of all that code later? That’s where comments come in! They’re like sticky notes or secret messages in your code-helping you, your teammates, or even future you understand the logic, the twists, and the turns of your thought process. Today, we’re…

#설명

평소에 여러명에 의해 자주 수정되는 SI 프로젝트에서는 작성하지는 않지만 가장 기본적인 내용이므로 기억해둘 내용이다

Java : Types of Comments

Java comments are used to provide information or description about the class, statements, variable and method for future reference so that easy to understand code for future enhancement. Java comments statements don’t compile. It also helps to hide unused code.

Types of Java Comments

Java supports 3 types of comments statments:

Single Line Comment

Multi Line Comment

Documentation Comment

Single…

Ever wondered how the future of JavaDoc might look like?

How about this: Markdown instead of HTML.

Try it now - in Xtend with these few lines:

@Active(DocProc) annotation Doc { String value } class DocProc implements TransformationParticipant<MutableMemberDeclaration> { override doTransform(List<? extends MutableMemberDeclaration> annotatedTargetElements, extension TransformationContext context) { annotatedTargetElements.filter(MutableAnnotationTarget).forEach [ val annot = findAnnotation(Doc.newTypeReference.type) val markDown = annot.getValue("value") as String val proc = new MarkdownProcessor val html = proc.markdown(markDown) switch (it) { MutableMemberDeclaration: docComment = html } removeAnnotation(annot) ] } }

Result:

Use static instead of www

You couldn’t use links like www.javadoc.io/doc/org.bla.bla.bla/artifact/version/SomeClass.html, you should use links like static.javadoc.io/org.bla.bla.bla/artifact/version/SomeClass.html.

But if you run javadoc it returns the error message

Error fetching URL: http://static.javadoc.io/org.bla.bla.bla/artifact/version/package-list

How avoid the fetching error?

Use linkoffline (offlinelink in Maven). But you need to unpack the javadoc of desired dependency.

Example for org.pegdown:pegdown

Welcome to another issue of Clojure Weekly! Here I collect a few links, normally 4/5 urls, pointing at articles, docs, screencasts, podcasts and anything else that attracts my attention in the clojure-sphere for the last 7 (or so) days. I add a small comment so you can decide if you want to look at the whole thing or not. That’s it, enjoy!

Clojure - metadata Clojure offers the possibility to attach a map to many Clojure objects (look for the implementation of the IMeta interface). The content of the map and a few functions to handle it goes under the name of "metadata". Metadata are used heavily in Clojure internals for debugging, documentation or directives to the compiler (and many others). Another use is in the basic Clojure testing facility which relies on the presence of the keyword ":test" in the metadata to know if the function should run as a test or not. Metadata can be used as annotations to help tools and libraries do their job avoiding the visual cluttering of additional parameters.

javadoc from the repl - How to launch javadoc in your REPL Nice easy trick to be able to quickly see JavaDocs directly from your REPL by Malcolm Spark. This builds on the clojure.java.javadoc/javadoc feature in the standard library that simply opens up the javadoc related to a Java class. javadoc knows where the javadoc is stored on your hard drive or where to go on the internet to find the docs. Just add the simple line to the lein profiles to have the command always available.

Lisp Meetings Calendar Zach Beane (of Quicklisp fame, a package manager for CL) maintains a list of the next Lisp meetups around the globe as a share google calendar. This is then featured as a side column of the planetlisp web site. I was wondering if I could find any in London but there's none in the whole of the UK apparently. Lisp could be not that used in the industry, but still worth learning.

Functional Geekery Episode 28 – Tom Stuart Thanks to this Functional Geekery episode I got to know about Tom Stuart and his work on the theory of computation and computer science in general. Tom wrote a book on "computation" with Ruby examples and he's a prolific speaker. The computation topic includes things like lambda calculus, decideness, cellular automata, algorithms, complexity and so on. Tom organises a computation-club in London where these interesting topics are discussed.

9th European Lisp Symposium Just noticed the 9th European Lisp Symposium has been announced and will be May 9th 2016 in Kraków (again! It is indeed a wonderful city and apparently conference hub :). Clojure is mentioned along with the other historical Lisp dialects as part of the potential program. All dates are still to be decided, stay tuned for the next announcements.

In a project I work I sometimes find crude code as many other people do. For me, a unit test is also a living documentation of the behaviour of the code.

Here are some of my "higlights" of code written by an international well known contractor. Please do not blame the employees, as I am sure the problem is also about management, goals and priorities.

Ignore failures

To write a test is sometimes hard work so I really don't understand why to make it completly useless with the following code fragment:

@Test public void testWhatever() { try { … } catch (final Exception exception) { Assert.assertTrue(true); } }

But findbugs is happy with this as the catch block is not empty. And of course, the test will never fail! And it creates a good coverage! Perfect!

Most of the other tests contain a assertNotNull() as the best case. But I think the goal was just "write tests that pass and have a high coverage".

Cluttered Code

I have no idea why, but I also found javadoc and trace logs in unit tests:

/** * Test something. * * @throws IOException Signals that an I/O exception has occurred. */ @Test public void testSomething() throws IOException { if (LOGGER.isDebugEnabled()) { LOGGER.debug("Inside MyTest->testSomething()"); } … if (LOGGER.isDebugEnabled()) { LOGGER.debug("Exiting MyTest->testSomething()"); } }

The build tools I use create test reports and I like test method names describing the tested behaviour so I don't need additional documentation.

Mock as mock can

When creating unit tests it is essential to mock dependencies so you can control them and be sure any error is not elsewhere. But you can also do too much:

public class MyHelperUnitTest { @Mock private UnitsInDTO unitsInDTO; @Mock private List<unitsindto> unitsInDTOList; @Mock private LocationModel locationModel; // 21 more mock declarations … @Before public void setUp() { Iterator<unitsindto> unitsInDTOIterator = Mockito.mock(Iterator.class); Mockito.when(unitsInDTOList.iterator()).thenReturn(unitsInDTOIterator); Mockito.when(unitsInDTOIterator.hasNext()).thenReturn(true).thenReturn(false); Mockito.when(unitsInDTOIterator.next()).thenReturn(unitsInDTO); // 70 more lines of behaviour definition …

I like Mockito very much but mocking a list of DTOs, sorry, this is not clean code! It is good if you know how to use a mocking framework, but it is even better if you also know when.

Conclusion