Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I'm working on a project written in Java, designed to transmit data via a messaging system that strictly defines the bit position of the messages fields. This means we have an entire library of dictionary classes designed to bit-shift object input data to/from the message binary representation. This library is reasonably large, and because the protocol is still young, has the tendency to be tweaked and changed every year or so.
The JavaDoc for this library provides ASCII art tables and diagrams that explain what a particular method expects as input (or output). These tables are exceedingly important because finding the documentation and verifying that the method actually does what the document says can be time consuming a prone to error. Following a single, simple ASCII-representation of the bit shifting makes this a lot easier.
I have a coworker who insists that ASCII art does not belong in JavaDoc (even with tags), and furthermore that we configure Eclipse to automatically format the code on save. He offers two options to reformat the documentation:
Embed an image.
Use an HTML table.
The image would be okay, except Eclipse doesn't render SVG images. It is completely unacceptable to me that we maintain an SVG image and then export the image as PNG to our documentation repo, and then link the PNG with HTML. The amount of maintenance involved in that scenario seems completely crazy. Who is responsible for making sure all the PNG, SVG, and code are synchronized?? Furthermore, obviously, the data won't be readable without the image.
The HTML table option is bad for two reasons. First, the Eclipse formatter puts each tag and value on it's own line, which means every single value takes up three lines. It leaves huge gaps in the source code, and is completely unreadable without rendering the HTML. To make matters worse, some of our tables are complex, and troubleshooting HTML tables is not my idea of a responsible thing to require of developers who already resist creating documentation.
So if my coworker is right about "java people" not using ASCII diagrams for documentation, what is a standard, industry practice, that gives us a method for preserving these diagrams? How does this method benefit over using tags with ASCII diagrams? Bonus points if you can answer why JavaDoc hasn't evolved to provide readable markup, instead of relying on HTML.
Edit: I just found markdown-doclet. I don't know if this will be an acceptable compromise or not. Maybe there are other tools that work similarly?
An old question, but I have had similar frustrations.
You can use the /*- construct to prevent Eclipse from formatting a given comment. See: https://stackoverflow.com/a/5466173.
Use the {#code} construct and/or <pre>. See: https://stackoverflow.com/a/542142. I suppose someone who argues against ASCII diagrams in general would argue against these, too. But perhaps it's having been enshrined in Javadoc syntax will be a point in your favor.
Point out that even the Java developers use ASCII diagrams where appropriate.
You could also tell your fellow to use a better editor. No, no, I troll (: ...A little.
At the company we've decided on ASCII diagrams for the primary reasons given already, and we believe they are more than enough to justify this choice:
Maintenance cost and feasibility. I've seen projects with outdated external resources... it's almost inevitable.
Displayed anywhere (IDE, text editor). We don't produce Javadoc for internal projects and put them on a web server. Development habits have changed... see http://www.flowstopper.org/2014/12/graphical-visualizations-in-javadoc.html
ASCII diagrams also force one to keep it simple, which usually helps for clarity.
I've found http://www.asciidraw.com/ to be a great tool for this purpose.
Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 3 years ago.
Improve this question
So is a decompiler really a thing that gives gives the source of a compiled/interpreted piece of code? Because to me that sounds impossible. How would you get the names of the functions, variables, classes, etc if it is compiled. Or am I misinterpreting the definition? How does it work? And what is the general principal behind making one?
You're right about your definition of a decompiler: it takes a compiled application and produces source code to match. However, it does not in most cases know the name and structure of variables/functions/classes--it just guesses. It analyzes the flow of the program and tries to find a way to represent that flow through a certain programming language, typically C. However, because the programming language of choice (C, in this example) is often at a higher level than the state of the underlying program (a binary executable), some parts of the program might be impossible to represent accurately; in this case, the decompiler would fail and you would need to use a disassembler. This is why many people like to obfuscate their code: it makes it much harder for decompilers to open it.
Building a decompiler is not a simple task. Basically, you have to take the application that you are decompiling (be it an executable or some other form of compiled application) and parse it into some kind of tree you can work with in memory. You would then analyze the flow of the program and try to find patters that might suggest that an if statement/variable/function/etc was used in a certain location in the code. It's all really just a guessing game: you'd have to know the patterns that the compiler makes in compiled code, then search for those patterns and replace them with equivalent human-readable source code.
This is all much simpler for higher-level programs like Java or .NET, where you don't have to deal with assembly instructions, and things like variables are mostly taken care of for you. There, you don't have to guess as much as just directly translate. You might not have exact variable/method names, but you can at least deduce the program structure fairly easily.
Disclaimer: I have never written a decompiler and thus don't know every detail of what I'm talking about. If you are really interested in writing a decompiler, you should get a book on the topic.
A decompiler basically takes the machine code and reverts it back to the language it was formatted in. If I'm not mistaken, I think the decompiler needs to know what language it was compiled in, otherwise it won't work.
The basic purpose of the decompiler is to get back to your source code; for example, one time my Java file got corrupted and the only thing I could so to bring it back was by using a decompiler (since the class file wasn't corrupted).
It works by deducing a "reasonable" (based on some heuristics) representation of what's in the object code. The degree of resemblance between what it produces and what was originally there tends to depend heavily upon how much information is contained in binary it starts from. If you start with basically a "pure" binary, it's generally stuck with just making up "reasonable" names for the variables, such as using things like i, j and k for loop indexes, and longer names for most others.
On the other hand, a language that supports introspection needs to embed a great deal more information about variable names, types, etc., into the executable. In a case like this, decompiling can produce something much closer to the original, such as typically retaining the original names for functions, variables, etc. In such a case, the decompiler can often produce something quite similar to the original -- possibly losing little more than formatting and comments.
That depends on what language you are decompiling. If you are decompiling something like C or C++, then the only information provided to you is function names and arguments (In DLLs). If you are dealing with java, then the compiler usually inserts line numbers, variable names, field and method names, and so on. If there are no variable names, then you would get names like localInt1, localInt2, localException1. Or whatever the compiler is. And it can tell the spacing between lines, because of the line numbers.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
in private and in companies it is over and over again a problem that I or we developers comment in fact our code but generally nobody knows exactly how the code of the whole project works together. When I write my own code and the project is getting bigger I sometimes have this problem too. Although I write tons of comments, after 3 months you don't know what the whole thing exactly does, that means how the different methods and classes work together.
How do you solve this in your company or in private (if there is just marginal project development and no requirements specification). Or do you have always such a good project development with contract document and requirements specification that you don't have to worry about that?
Code complete can explain the solution to your problem better than I ever could.
I find the best way to solve this is to write a functional test using a unit test framework.
In a functional test you write a test which loads up several if not all the core components laid bare. This shows that all the components work correctly together but also you get a documents which shows you in one place how everything connects.
Depending on how complex you interactions are, you may not be enough and you need to document it. Personally I would prefer to make the code simple so that documenting it is not really needed or is relatively easy to explain.
If documenting it sounds too hard, its time to refactor your code so that its not.
Take your time a create some short and simple design documents, add some UML diagrams to just show the basic ideas behind the whole application. This would give new team players a quick overview. Publish this documentation on an internal wiki and encourage the team to enhance, if necessary.
Then, as Peter suggested, some well documented test cases really help: Read the test code and learn how to use the API. (and, as a secondary effect, test the code ;-) )
I would not put too much effort on comments, especially on line comments. The tend to become out dated, because no unit test verifies that line comments are still valid and, even worth, no one ever deletes unnecessary comments.
Good question. Part of what you are asking relates to code maintainability. In my view the two main things you can do to improve this are:-
Write some design documentation
Develop maintainable and clearly written code
From past experience the first item is very often neglected on software projects due to time constraints, but I think that if you can produce at least a class diagram of your system, then this is worth a lot in terms of understanding how objects interract when you revisit the code in a few months. Depending on the complexity, then sequence diagrams can also be useful. Producing this documentation will also be of benefit to new members of the team, in quickly having an overview of how the software is structured.
I can't stress enough the importance of writing clear and maintainable code. My eyes were recently opened when I read Clean Code by Robert Martin. You owe it to yourself and your fellow developers to read at least the first couple of chapters in this book. That alone will immediately improve the readability and maintainability of your code.
The idea is that the code should read almost like a narrative, where methods follow in a logical order, are short, appropriately named, and take few parameters. Doing this almost eliminates the need for code comments, and improves the code structure.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 7 years ago.
Improve this question
I am curious enough to considering not evening writing certain code in Java because of how easy it is to decompile. Is there a way that I can write in Java and not have to worry about decompilers? I understand anything can be reversed engineered given enough time, so what I am asking is: are Java class obfuscators effective enough to deterrent decompliation?
are Java class obfuscators effective enough to deterrent decompliation?
I would say "no". When I decompile source code with the intent of trying to figure out how someone did something, I already know what I'm looking for. So I don't have to understand the entire program -- just the one piece that's of interest to me at the time. With enough puzzling over methods and backtracking a bit up the call chain, it's usually possible to determine what's under the hood without an excessive amount of effort.
If your question is Can I ensure that no one can hack my code , the answer would be NO..
Whether it is in JAVA or Visual C++ .
As long as your software which is made up of byes or bits is directly accessible by the hacker.
The REASON is simple.
However you encoded , that can be decoded.
The best strategy could be to make a web service and deploy your secret logic there.
Let others use your service without having access to how you wrote.
Obfuscation, in Java and other languages, is just a deterrent. It simply raises the bar for the attacker. That doesn't mean obfuscation has no value, it just isn't a guarantee.
What are you trying to protect and what type of market are you targeting ?
Obfuscation to protect a license algorithm in a market that it full of pirating isn't going to mean that much. However, for SMB, it may be a enough to cut out most of the casual pirates.
If you are trying to protect IP from competition, I see two answers. The idea, will be hard to protect. A capable engineer looking at the code will figure out the gems of the logic and be able to reimplement. Obfuscation will make it a lot harder for people to just pick up the code and include it in their own product. The maintenance costs will continue to grow as they attempt to make changes (I'd say that is also true for cleanly decompiled code).
The java products I develop for my company are obfuscated. Have they protected us from theft...I doubt it. But, in the context of our development costs, the obfuscation wasn't that expensive. A small bit of protection for a small price isn't a bad trade-off.
From personal experience decompiling Java, I will say that obfuscation can make someone's attempts to decompile very very irritating and difficult. The most irritating to me is when the final builds class files are all named "a.class, b.class, c.class" and so on, and a large amount of dummies are thrown in. In terms of in code obfuscation, try/catches do a fine job of messing stuff up for the decompiler.
In general, anything you decompile will not be compilable, but will give you hints as to the general workings of the program.
"Effective enough" depends entirely on how effective you need it to be. And that depends on what you are protecting, and from whom. None of the conventional methods (obfuscation, encrypting the bytecodes, compiling to an "exe") will stop a skilled and determined attacker with enough time and incentive. But that pretty much applies to all forms of programming. (You can disassemble or decompile C/C++ apps as well ...)
The only way you can protect against a serious reverse engineering effort is to use a secure execution platform; e.g. using something based on TPM. Even then, if the bad guys can attach a logic analyser to a system running your code, they can (in theory) capture the native code being executed and then start on the reverse engineering path.
EDIT : Someone has reportedly succeeded in breaking a popular TPM chip, using an electron microscope; see this Register article. And interestingly, his original motivation was to hack Xbox 360 consoles!
Frankly speaking No. No matter how ridiculously you obfuscate the code, if someone knows he can make a million dollar out of your code, he will decompile your class files and get the code.
There are alternatives though:
Convert your java program to exe beofre distributing. You must know that there are catches here.
Encrypt you class files with a key. Make a custom classloader that can decode the class files using the private key before loading it into memory. There are two problems here, a) load time increases, b) how will you hide the private key.
if you read my post https://stackoverflow.com/a/26717791/2132826 you will see that I couldn't find one good java de-obfuscator that actually works as expected.
so the current answer is: NO.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
I just realized from an article in CACM that Doxygen works with Java (and several other languages) too. But Java has already the Javadoc tool. Can someone explain what are the pros and cons of either approach? Are they mutually exclusive? Is there a Maven plugin for Doxygen?
Doxygen has a number of features that JavaDoc does not offer, e.g. the class diagrams for the hierarchies and the cooperation context, more summary pages, optional source-code browsing (cross-linked with the documentation), additional tag support such as #todo on a separate page and it can generate output in TeX and PDF format.It also allows a lot of visual customization.
Since Doxygen supports the standard JavaDoc tags you can run Doxygen on any source code with JavaDoc comments on it. It often can even make sense to run on source code without JavaDoc since the diagrams and source code browsing can help understanding code even without the documentation. And since the JavaDoc tool ignores unknown tags you can even use additional Doxygen tags without breaking JavaDoc generation.
Having said all this I must admit that I haven't used Doxygen for a long time. I tend to rely heavily on my IDE nowadays to provide the same visualization and I usually don't read JavaDoc as HTML pages but import the source files into my IDE so it can generate JavaDoc flyouts and I can jump to the definitions. That's even more powerful than what Doxygen has to offer. If you want to have documentation outside the IDE and are happy to run non-Java tooling then Doxygen is worth a try since it doesn't require any change to your Java code.
I'd only use Doxygen with Java if you're new to Java and you've used Doxygen before, reducing the learning curve you'd experience with javadoc. If you haven't used Doxygen before, I'd stick with javadoc, since it was specifically designed with Java in mind. If you don't know either one, and you work in C++ (or other supported languages) as much as you do Java, Doxygen is a good choice, as you'll be able to use it for both languages.
Both tools are easy to use, with a similar feature set. Both have plugins (or are pre-built in) for NetBeans and Eclipse making it even faster to generate doc. There is a lot of overlap in the comment style used by each, but they're not exactly the same, so it would be difficult to mix them together (you'd have to know the details of both, leaving out any features that are specific to one or the other). I've never used it, but there does seem to be a Maven plugin for Doxygen.
I like the fact that with Doxygen, you can get class diagrams displayed on the same page as the documentation. Also, I like the fact that it links you directly to the source code, if needed. I am not aware if javadoc has these features though.
One big advantage of JavaDocs is that they just work. Everything needed to build and view them is included in the JDK that you already need to have installed for compiling your programs.
Doxygen, on the other hand can be a pain to set up and get working correctly. but if it is set up correctly it should be able to generate PDFs, RTFs, and DocBooks, as well as HTML. The HTML is not organized as well by default as JavaDocs since the index.html brings up a blank page by default. Also, inline classes and static members may need special flags to be included in documentation, and if you want to generate a PDF you may have to deal with hassles of your distribution of Linux not having the needed pdflatex command (e.g. Ubuntu/Mint have had problems recently) so if you just apt-get install it and run you may get a screen full of errors even with a simple program. Compared to the ease of getting javadoc automatically when you install the API, Doxygen setup can be a miserable experience. Once you overcome the hurdles, it should be more flexible in dealing with projects involving more than just java, though.
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 10 years ago.
Improve this question
I'm working on getting an Introduction to Groovy presentation ready for my local Java User's Group and I've pretty much got it together. What I'd like to see is what you all think I just have to cover.
Remember, this is an introductory presentation. Most of the people are experienced Java developers, but I'm pretty sure they have little to no Groovy knowledge. I won't poison the well by mentioning what I've already got down to cover as I want to see what the community has to offer.
What are the best things I can cover (in a 1 hour time frame) that will help me effectively communicate to these Java developers how useful Groovy could be to them?
p.s. I'll share my presentation here later for anyone interested.
as promised now that my presentation has been presented here it is
I don't know anything about groovy so in a sense I've qualified to answer this...
I would want you to:
Tell me why I would want to use Scripting (in general) as opposed to Java-- what does it let me do quicker (as in development time), what does it make more readable. Give tantalising examples of ways I can use chunks of scripting in my mostly Java app. You want to make this relevant to Java devs moreso than tech-junkies.
With that out of the way, why Groovy? Why not Ruby, Python or whatever (which are all runnable on the JVM).
Don't show me syntax that Java can already do (if statements, loops etc) or if you do make it quick. It's as boring as hell to watch someone walk through language syntax 101 for 20min.
For syntax that has a comparible feature in Java maybe show them side by side quickly.
For syntax that is not in Java (closures etc) you can talk to them in a bit more detail.
Remember those examples from the first point. Show me one, fully working (or at least looking like it is).
At the end have question time. That is crazy important, and with that comes a burden on you to be a psuedo-guru :P.
I'm not sure about how the Java6 scripting support works but I'm fairly sure it can be made secure. I remember something about defining the API the script can use before it's run.
If this is the case then an example you could show would be some thick-client application (e.g. a music player) where users can write their own scripts with an API you provide them in Groovy which allows them to script their app in interesting and secure ways (e.g. creating custom columns in the playlist)
I'd go for:
Closures
Duck typing
Builders (XML builder and slurper)
GStrings
Grails
I'd mention the following things in addition to what has already been stated:
GDK - extensions/additions to existing JDK classes
Interaction between Groovy and Java code (basically a non-issue)
Compiling Groovy code to Java .class files
XML parsing and mechanisms for accessing document content
One thing I like doing with Groovy is implementing an interface defined in Java as a map from method names to closures. It's a cool thing you can do with Groovy, but probably well beyond an introductory presentation though.
Include an example of how making Java code more groovy takes away soooo much code. Wait for them to pick their jaws up off of the floor before continuing. Scott Davis has a simple example at the beginning of Groovy Recipes that takes 35 lines of Java or 3 lines of Groovy.
You should definitely show them how to create a quick Grails application. Two domain classes that are related. Build a basic CRUD app. Explain that tables are being created behind the scenes using GORM(Hibernate). Then explain that you can create a war file and deploy it as you would any other Java war file. You can also add Grails/Groovy to an existing Java/JSP project so it doesn't require a huge commitment or paradigm change.
Groovy/Grails is simply Ruby/Rails for Java people. I'd cover the plugins for Netbeans/Eclipse too. Groovy/Grails are just now getting full support in the major IDE's.
Finally, if you can find a good diagram that shows how Grails is built on top of Spring, Hibernate, Quartz, Sitemesh and Groovy, I think people will understand that there is a treasure chest waiting to be unlocked.