I need to document a Java project. I am a C# Programmer and Systems Analyst. But I am new to Java.
I have the directories checked out of SVN.
These directories include the source directories, WEB-INF and other files required for definition of the project, classpath etc.
I understand that the files essentially belong either of the following three categories
Source code files / directories that are based on the way the packages are structured (.Java)
Directories / Files required for project definition, compiler settings etc
Files required for deployment.
The project is (as most Java projects are) an Eclipse based project designed to be hosted on Tomcat.
Now, give the above information I have decided to document the entire project into three different documents
A document explaining the source code etc.
A document explaining the purpose of the files & directories that are required for compiler settings, project definitions etc
A document that explains the deployment directory structure.
Or alternatively I could create a single document with three sections that explain 1-3 above.
Now, questions
Is this the right approach?
Are there any other methodologies that I can follow or borrow from?
Are there any other suggestions etc that you can add to this approach
Any additional info will be of use.
Thanks a ton in advance
I think you're on the right track. In a project you need to address three documentation needs
User Documentation
This include a document stating what the application is about, and how to start it/access ut.
Development Documentation
This includes at least the Javadocs, a description of the source code directory structure, the build process (ie, how to compile the project), compiler time dependencies, development standards, how to set up a database for development, and how to get the source code from the repository. These are the minimum you need to get others to work in your project. Additionally as the project complexity grows I like to put together a series of "How To" for common tasks in the system (ie: "How to leave an Audit Trail for a given Operation", "How to use the Logging framework", "How to manage exceptions", etc), a description of the main Domain classes and their relationship. If you use a database, and the database schema is not exactly one-on-one with the domain classes, I'll add a schema documentation.
Deployment Documentation
This is basically the installation manual of the application, describing any steps needed to make it run: putting the WAR in Tomcat, running scripts against a database, configuration files that needs to be modified, etc,etc.
As you see, you already partially addressed two of them. Start small and simple, and add the rest as the need arises.
It also helps to check if your organization has any documentation standard.
Try Javadocs link. Written with proper planning, it will address all your points above.
A document explaining the source code etc.
Yes. Approach this as if your reader was someone trying to get familiar with the reasons why the project was written (why was this project created), as well as the overall architecture of the project.
The Javadocs on the source classes should explain what each class does. Your document should tie the Javadocs together, like a tutorial.
A document explaining the purpose of the files & directories that are required for compiler settings, project definitions etc.
Yes.
A document that explains the deployment directory structure.
I suppose that's what your build scripts do. Perhaps I don't understand what you expect this document to accomplish.
Are there any other suggestions etc that you can add to this approach
Unless this is the first time anyone in your development group has documented a Java project, there should be other documentation. See what they've done.
If you are the first, then I'd say this was a good start. I'd be most interested in the first document. Your new programmers would like the second document.
Related
I'm trying to understand the file structure in Netbeans.
For example: I want to create a new class. I do so by right clicking the navigation bar, and get prompted to name my new class. A warning appears with the words "It is highly recommended that you do not place Java classes in the default package"
So,
What does go in the "default package"?
What goes in the Test Packages and Test Libraries folders?
If I have some text files or some such thing for my program to read, where should they go?
I'm taking some online courses on Java, but these sort of nuances aren't covered in the classes. I want to start doing it right, right now, so I don't have to untangle all of my files later on down the road.
You should refresh your understanding by reading the tutorial.
The default package is a package that gets created for your project. It's OK to organize your files under the default package, but if your work is somewhat serious, you're going to want to place them under a named (and therefore non-default) package, like com.myorganization.myproject as per the tutorial. NetBeans will also allow you to refactor (rename) an existing package. Left click, hit F2 and supply a new name.
Test packages and libraries used to test your project go in the Test Packages and Test Libraries directories. It sounds like you're a ways off from testing with frameworks like JUnit, however, so you needn't concern yourself with those things just yet.
If you have arbitrary data files, you can really put them wherever you can find them later. If you're working with Android, for example, you'd have a /res directory just under your project root with resources like images, icons, data files, etc. You can create your own resources directory, or you can be lazy and dump them directly in the project root. Wherever you put them, you have to make sure you call them correctly using absolute or relative paths.
If you're using online courses, especially if you're paying for them, use the resources they provide, like live tutors or their forums. This kind of fundamental/tutorial help is a bit below the threshold for Stack Overflow.
I've been working on a Maven project consisting entirely of Java, and lately started to mix Scala code into it.
I'm amazed by the great expressiveness Scala offers, the easy use of scala-maven-plugin, and especially the incredible interoperability between Java and Scala.
However, I hit one inconvenience; according to the Maven's convention, Java's source code goes into src/main/java, whereas Scala's into src/main/scala. I found it quite cumbersome because I have to frequently go back and forth Java and Scala source files and every time I have to traverse the deep hierarchy of package directories (I often close tabs to keep my editor from cluttered).
So the question is: Is it recommended to maintain separate directories src/main/java and src/main/scala? If so, why?
To add more background, I've been working on the web application framework Wicket, whose convention is to put the HTML files alongside with their corresponding Java files. If we keep the directories separated, naturally the HTML files are separated as well (I don't think putting Scala files and corresponding HTML files in different directories makes sense). And then it goes "why I can't find Foo.html? Oh, I was looking for the wrong directory."
The source files themselves are very easy to distinguish both by humans and by machines by inspecting their extensions. I configured pom.xml to handle both Java and Scala put together in src/main/java and it worked (compiles and runs). On the other hand, separating directories poses a risk of defining conflicting classes in Java and in Scala, a careless mistake.
Well, I don't want to name a directory java if it contained not only Java's but also Scala's. But this is the only point I can come up with for separating directories.
(Edit: I've come up with a workaround-interpretation; let us think java stands for Java Virtual Machine. In this way, having src/main/c doesn't contradict if we ever decided to use JNI because C doesn't run on JVM.)
Oh, and one more point; my project is not intended as an open-source project; development convenience is preferred than trying hard to follow conventions.
This question is inspired by this answer.
I'd say yes, re-use code as much as possible. Maybe in future you can use this Java piece somewhere else...
As you probably know, you can use Java in Scala projects but not Scala in Java projects. So in this specific example it will help you with (future?) Java projects. If you want to re-use a piece of your Java code you can do that in either Java projects as well as Scala projects.
So i.m.h.o. it doesn't stop at the src/main/... but you should really put them even in different components.
Btw, little side note: if I'm correct, Wicket allows you to put the html somewhere else too, even in a different project... I saw it being handy (only) once, where we had to create different frontend for different clients of us. The java code stayed the same, the wicket-id's as well, but the html changed everywhere. Though it did give us some problems as well using the Qwicky plugin, as it could not find the html files in our IDE anymore.
We have an API for OSX that we offer in 3 different languages;
Objective-C, C++, and Java.
For the C++ and The Objective C Languages we use Doxygen for all of the documentation. The same nice looking presentation that is applied to the class pages is also provided for the examples page (mainpage.h). I especially like the syntax coloring.
For the Java Language, we are using Maven. Since apple's dev environment doesn't really offer much for Java, we can use Maven for both documentation and its a decent build system as well. The class pages look as good as Doxygen in my opinion, but the presentation of the main examples page(examples.apt), looks pretty plain and uneventful.
Ive been searching for any reference on how to add some color to the page, but haven't really found anything.
My question:
Can anyone provide an example of how to implement coloring in the appropriate .apt file(examples.apt) or the sites.xml file?
There are two main locations for customizing the Javadocs. The first in in the pom.xml files. The second location is in the src/main/javadoc directory. You will probably have to create the src/main/javadoc directory yourself since it isn't normally in the initial set of directories.
See https://github.com/BradleyRoss/tutorials for how I set up some Javadoc settings. Look at the pom.xml in the parent module and the src/main/javadoc directory in tutorials-common module.
See https://maven.apache.org/plugins/maven-javadoc-plugin/examples/stylesheet-configuration.html for information on how to replace the stylesheet.css file with your own. That is probably where most of the color selection would go. It uses the stylesheetfile and stylesheet tags in the configuration section for the Javadoc plugin.
Maven apparently uses a modified version of the stylesheet.css file that comes with the JDK. You may want to compare the JDK and Maven versions to get some ideas on what you can change.
Looking at the jOOQ example of the Maven plugin configuration for the code generator (near the end of the configuration), I see that the target directory for the generated files is target/generated-sources/jooq.
Since the generator produces Java code, do you know why the suggestion here isn't a subfolder of /src, but instead a completely separated one? Is there any reason for this? Is it a best practice or something?
This is a good question and should probably also be covered in the jOOQ manual!
The question is not strictly related to jOOQ but to source code generation in general (e.g. also when using XJC to generate JAXB-annotated Java code from XSD). Some people prefer making generated source code part of the "main" source code, others prefer to keep it apart. There are essentially these ideas behind each approach:
Keeping things separate (e.g. target/generated-sources)
The only "source of truth" is the database schema. No copies thereof are ever stored in source form, only in binary form.
Source code generation becomes an integral part of your build. Everyone building your application (developers, continuous integration) will need to re-generate the sources. This will ensure that sources are always up to date.
Keeping things together (e.g. src/main/java)
The same "truth" is duplicated between the database schema and the generated copies thereof.
Source code generation is an "external" process, that isn't part of your build.
Generated sources are put under version control, where they are expected to be up-to-date.
Such version-controlled sources can be monitored for database changes, in the case of jOOQ.
There isn't really a generally preferred way. Both have their advantages.
I want to find a library that I can use from my Java application that will allow me to access specific Javadoc in the scope of my project (I specify where Javadocs are located). Just like in Netbeans, I want to potentially access the Javadoc from html files locally and remotely, and from source.
I expect that I could use code from Netbeans to achieve this, but I don't know how, and I can't easily digest their documentation.
Today I started thinking about the same thing.
From CI point of view, I could use #author annotation to send e-mail to someone, who wrote a test that is failing with error, not with a failure.
Google didn't help me (or I didn't google deep enough), so I started wondering how to do it on my own.
First thing that came to my mind is writing a little tool that will check all *.java files specified in a directory, bound file name to annotations and allow user to perform some actions on them.
Is that reasonable?