I"m having to work with legacy code (mostly CFML) with very little or no documentation, no domain model of any sort to follow either.
To start building some sense out of it, I though 'start keeping notes', then wondered if plain old journal and pencil for text notes would do. Maybe a text document (searchable). Or is it best to take the plunge and UML the beast over time? If that's an overkill on one hand, on the other I repeatedly find myself feeling around the elephant over and over again. How do you build a up a map of the territory?
Sorry for the late answer, but I've ended in situations like this couple of times before. I'd suggest you not to create UML for that, since it will take much time and this code is not very nice, as you've noted (no domain model, no structure).
You could use pen and paper, or text file. Browse through the code, find the most important parts for you and write down where it is located, with some description. If there is no data structure, you could use file name, module, line number, etc. After spending some time doing this, you will have something like navigation plan for the part of the system and general understanding of how it works.
Also, you should refer to this question, there are some answers that can be useful.
Related
Does anyone know of an OTF macropad out there? Like a macropad with an on the fly record button similar to what you find on razer/redragon keyboards? I'm a data scientist working for a startup still trying to get everything organized. There are many times where I have one-off, heavily repetitive tasks where automation is not a pragmatic solution. Every macropad I've seen requires you to manually write your own macros or to use some software interface, which is fine if the macros will be permanent, but mine will all be temporary. I've looked everywhere, but I can't find anything.
There are quite a number of modules on CPAN relating to the creation and manipulation of .pdf files, and I'm hoping this community can save me some time going down blind alleys.
I am looking to create .pdf files from scratch, with only simple formatting such as bold/italic and left/right/center justify. Being able to use a template file would nice, from an MVC perspective, but if the best module doesn't support that, I'm ok. I want the best module for my narrow problem set.
Edit: let's add the constraint that it does have to be a Perl module, if not a pure-perl solution. Thanks for answers thus far!
Update: PDF creation is one difficult problem to decide how to approach. In addition to the good suggestions here, there seems to be about 1,000 different ways to solve this, and knowing which solution(s) to invest your time in is a real challenge. It is easy to acquire dependencies on outside executables in the process of building this solution, which is why I have been favoring doing everything in Perl if possible.
I went down the road of trying to use PDF::Create but found it too limiting. You have to give coordinates to place each string of text and there is no built-in concept of text wrapping... this is all work you have to do. Impossible amount of overhead for my task.
I am now using PDF::API2, which is much more powerful than PDF::Create, but still demands the PDF be assembled at a troublingly low level. Luckily, there is some help online. See Rick Measham's excellent PDF::API2 tutorial with accompanying text_block() subroutine, which thankfully does the heavy lifting on the text wrap problem.
Unless you see another update here, this is the solution that ended up working for me.
I'm the author of the CPAN module CAM::PDF which is definitely not the best tool for this job -- it's designed for high-performance editing, not creating.
Among free PDF creation libraries, I like PDF::API2 the best. It has a very rich feature set and good encryption support (inspired by CAM::PDF I might add!) The author, Alfredo, manages a popular email list. People sometimes complain about documentation, but I've found it to be adequate.
Among commercial libraries, I've had good experiences with pdflib.
Three modules for creating PDF come to mind (in no particular order)....
PDF::API2
PDF:::Create
PDF::Template
PDF::Template gives you that template option you maybe hankering for? PDF::Create seems more straightforward (at least from the docs) and may meet your "simple formatting" requirement more adequately.
However if you want to know what the "community" thinks then only PDF::API2 gets a rating on CPAN Ratings coming in with 4 out of 5 stars overall score.
Hope that helps.
PS. Disclaimer: I've not used any of these modules. In past I've always gone for XML/XSLT/XSL-FO using Apache FOP with Perl being used to create the initial XML data. This can be an overkill for something small and not always ideal if you want to embed PDF generation into your Perl app.
PPS. So I'll also be looking at these CPAN PDF modules at some point in near future!
Does it have to be a Perl module? You could always use LaTeX and convert that to PDF. Not quite as straight-forward, but it is another option.
G'day Marcus,
Glad you found the tutorial. I do a lot of work in PDF::API2, so if there's anything I can help with, just let me know.
Naturally, I recommend PDF::API2!
There's a guy Jay Hannah, who's currently turning the text block into a module for CPAN that does exactly what you want: bold, italic, etc. If you check the mailing list, you'll see his posts at the top.
Cheers!
Rick Measham
Yeah, tough to answer without knowing exactly what your constraints are. If pure-Perl is not a necessity, I'd be inclined towards DocBook.
The initial markup you'll generate can be very simple XML; and the transformation requires just an XSL processor and shelling out to something like Apache's FOP.
how to save a online pdf file using perl?
http://www.nwcc.bc.ca/FNC/pdfs/Stepping%20Stones%20to%20improved%20Relationships%20-%20web.pdf
I am using file::download. but the problem is its not downloading url with url encoded strings.
sharma
Has anyone used Powershell to generate a report of C# classes versus methods and properties? I'll admit up front I'm not attempting first to write this myself, but someone out there has probably already done it, or would highly enjoy doing it. The challenge will be recognizing things like method signatures across multiple lines. You could join the string array returned by gc and search on that to make it easier. If no one answers, I'll eventually post a solution, but probably many weeks from now.
Update: I'm looking for a Powershell solution because that's already my main scripting language, and I'd like to be able to make changes over time, perhaps extend it to cover JavaScript for example, or change the report format, and I'd like it to work with any version of Visual Studio and C#. I'm also looking for a text report, nothing graphical, so that it's more searchable and manipulatable. I like simple fully programmable free things that impose no limits. :)
Thanks,
Mike
I'm sure you can access Reflection through PowerShell.
You should also look into NDepend, which can do a lot of this sort of thing.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
As a developer I really don't like writing documentation but when I have to I'd like to make the process as painless as possible.
The problem with Word is that it constantly gets in my way. I worry more about the layout than about the actual content ... that's why I'd like to get rid of Word.
Ideally I'd like to write my content and then 'compile' it into a document.
I've heard of LaTeX but I don't have any experience with it whatsoever. Would this be the right technology for the job? What editor (Windows) should I use? Is it a good idea to start with LyX?
EDIT: I'm not asking about documenting code (I use Sandcastle for that).
Update 2014:
We have now switched to GFM (GitHub Flavored Markdown).
It's really easy to work with.
Write code & documentation in the same IDE!
Everything can be versioned!
Get great output either as raw txt, html or pdf!
My solution to this was to invest some time in creating a decent Word Template for myself.
The important thing to do is make sure you have a Style defined for everything you can put in the document.
Once you have all the Styles defined and all of the document content tagged with the correct Style instead of formatted in an ad hoc fashion, you'll be surprised how easy it is to produce good looking Word documents quickly every time.
The wider problem here is that everyone spends hours in Word and yet it is very rare for companies to invest in Word training. At some point you have to bite the bullet and take the time to teach yourself how to use it properly, just like you would with any other tool.
Anything you can do with LyX you can do with LaTeX. LaTeX is suitable for all sorts of things; it has been used for everything from manuals to lecture slides to novels.
I think LaTeX is probably worth looking into as an option; if you've ever wanted to "code" for your word processor, LaTeX is for you. At the simplest level you can define new commands to do things for you, but there's a lot of power there. And the output looks really neat.
In my opinion, LyX is fantastic in certain circumstances, handy in others, and occasionally just gets in your way. I think it should be seen as a productivity booster for LaTeX. In other words, learn to use LaTeX before trying LyX. Both are of course free and available for Windows, though the learning curve is quite steep compared with MS Word. For long documents, or plenty of similar documents, LaTeX/LyX is probably a worthwhile investment.
I've found that wikis can be good for this. Find a wiki you like that lets you do a bit of formatting, but nothing really heavy. Ideally it should let you format code easily too - to be honest, the markdown available on SO is probably a good start.
That way:
You have change tracking built-in (assuming a decent wiki)
You can edit from anywhere
Everyone always sees the same documentation (instant distribution)
You can concentrate on content instead of formatting
You could write your documentation using your own XML format and then transform it into any format with XSL (e.g. PDF via FOP+XSL-FO ).
See also the DocBook XML format.
LaTeX is an extremely powerful tool and might well be overkill here as it is designed for scientific/mathematical literature. It has a (relatively) steep learning curve and can be tricky to coax to do exactly as you want if you're new to it. I LOVE LaTeX, but it is not really a general purpose word processor.
Have you considered OpenOffice instead?
LaTeX is really a very powerful language if you need to write documents.
Perhaps you can try texmaker, a cross-platform LaTeX editor:
Texmaker is a clean, highly
configurable LaTeX editor with good
hot key support and extensive Latex
documentation. Texmaker integrates
many tools needed to develop
documents with LaTeX, in just one
application. It has some nice
features such as syntax highlighting,
insertion of 370 mathematical symbols
with only one click, and "structure
view" of the document for easier
navigation.
What about using HTML? This way you could then publish the documentation if there will be need for many people to access it from many places.
Despite all efforts and reasonable expectation I don't think Word Processing has been "solved" yet.
My response to what I also personally find a deeply frustrating experience with MS Word is to avoid it altogether and use an auto-documenting tool like GhostDoc to generate XML from what I've already written in the code (DRY!) and deal with the XML from an XSLT based intranet site or similar later.
Are you talking about documenting your actual code? If so, I recommend Doxygen for unmanaged code and Sandcastle for managed code. Both will compile your help or build it as a website for you.
Both applications will read special tags above functions / classes / variables and compile that into the help.
Well I've never found anything wrong with MS-Word in the first place. (i.e if you take the time to know how to use it effectively). OpenOffice indeed is an amazing & credible free alternative - but then if you hate MS Word for layout related problems, the same problem is gonna occur with OpenOffice too.
Never tried the Latex system myself, but have heard its good for scientific work. I think using some HTML WYSIWYG editor would be best for you, if you want to just focus on the content.
I considered a wiki, but I decided to go with a modified Markdown notation, for the simple reason, that a wiki's content isn't easily exported and distributed outside of the wiki itself, while the Markdown can be rendered into HTML.
Answer to chris' question about my workflow: I write the documentation with a Notepad-like application (TextWrangler, only because of its word-wrapping feature) in its raw Markdown format. Then I have a small localhost documentation website with my modified Markdown parser (extended for a few features and a bit more HTML-oriented functionality) that checks for the timestamps for the documentation files - if a file has been updated, it parses that file into HTML, and stores the file in a cache.
This way I'm able to edit the source documentation on my desktop, and just press F5 in my browser to see the results immediately.
I haven't got around to trying it yet, but I've always thought AsciiDoc would be good for this kind of thing.
If you want something simpler than LaTeX, you can have a look at ReStructured Text
Read this book: http://en.wikipedia.org/wiki/The_Pragmatic_Programmer . There is some idee fixe inside, so that documentation should be built automatically. Think about using your IDE for this, or look for some additional tools. Most modern languages support generating documentation as you write the code. This can simply maintain your doc in touch with latest changes in the code.
I prefer to use a RTF editor which is a lot less clunkier than words. This way the formatting and all the headers/footers nonsense will not take up half your time. Wordpad has worked for me on several occasions. I'm stuck with Word for now though :(
there are a lot of possible ways:
embedded documentation, e.g. javadoc: good for describing APIs, not so good for the "big picture"
plain html: can be checked in under version control, a definite plus
a wiki, e.g. confluence -- great for collaboration, but has version control different from your source
LaTeX or somesuch: better suited for books or papers than typical documentation; support for graphics is cumbersome
an Office clone, e.g. OpenOffice: mostly the same as Word+Visio, but open source, with a nicer document format
I usually document the software structure (the "metaphors" of a project, component interrelations, external systems) up front, using Visio, in "freeform" UML. These are then embedded in confluence, which can be converted to PDF if someone wants a printout.
LyX
LyX is a WYSIWYM front end to LaTeX: You get the convenience of a document processor (somewhat similar to Word) with the consistency and power of LaTeX: It doesn't get in your way and can do a lot of things that professional writers need.
Note: The correct answer for you really depends on your way of thinking --- we can't decide this for you. This answer simply shows an excellent choice if you think of documentations as documents and want something similar to Word (where Word is good) that doesn't suck as Word (where Word is bad for programmers).
But many programmers think of documentation differently and hence prefer different metaphors. I myself had the same problem years ago, worked with LaTeX (as I am a mathematician), found LyX and finally settled on a Wiki/Source system that I wrote myself.
Vim is the solution for anything that means writing plain text in the most efficient possible way. If you need formatting, then use XML, Latex or something similar (in Vim).
Vim changed my life!
Simple answer: LaTeX sounds like just what you are looking for.
I use it for writing documentation myself. I will never go back to Word if I have the option.
At phc, we started with latex, then moved to docbook, and have settled (permanently I hope) on Restructured Text/Sphinx.
Latex was chosen because we are academics, and latex is the tool of choice. I believe it didn't generate good enough HTML.
Docbook was chosen for power, but it was very unwieldy. It put us off writing any documentation: code had to be manually formatted, we kept forgetting the syntax, and it was difficult to read. The learning curve was also steep.
Finally, we moved to reST, using sphinx, and that was a great decision. Documentation is now very easy to write, and both PDF and HTML versions look beautiful (though the PDF could do with some customization). Its very easy to customize too.
The best bit about reST though, is that its human readable in source form. That is a wonderful advantage. I've switched to using reST for all my stuff now, especially anything over the web (except of course academic papers, where one would be foolish to use anything but latex).
You may want to look into doxygen at http://www.doxygen.nl/, see their nice examples. In this case, the documentation is presented by tags in comments in the source.
Another option would be to use an online system like trac from http://trac.edgewall.org/ which is a wiki/doc/issuetracking system that lives on top of subversion.
Having programmed through emacs and vi for years and years at this point, I have heard that using an IDE is a very good way of becoming more efficient.
To that end, I have decided to try using Eclipse for a lot of coding and seeing how I get on.
Are there any suggestions for easing the transition over to an IDE. Obviously, some will think none of this is worth the bother, but I think with Eclipse allowing emacs-style key bindings and having code completion and in-built debugging, I reckon it is well worth trying to move over to a more feature-rich environment for the bulk of my development worth.
So what suggestions do you have for easing the transition?
Eclipse is the best IDE I've used, even considering its quite large footprint and sluggishness on slow computers (like my work machine... Pentium III!).
Rather than trying to 'ease the transition', I think it's better to jump right in and let yourself be overwhelmed by the bells and whistles and truly useful refactorings etc.
Here are some of the most useful things I would consciously use as soon as possible:
ctrl-shift-t finds and opens a class via incremental search on the name
ctrl-shift-o automatically generates import statements (and deletes redundant ones)
F3 on an identifier to jump to its definition, and alt-left/right like in web browsers to go back/forward in navigation history
The "Quick fix" tool, which has a large amount of context-sensitive refactorings and such. Some examples:
String messageXml = in.read();
Message response = messageParser.parse(messageXml);
return response;
If you put the text cursor on the argument to parse(...) and press ctrl+1, Eclipse will suggest "Inline local variable". If you do that, then repeat with the cursor over the return variable 'response', the end result will be:
return messageParser.parse(in.read());
There are many, many little rules like this which the quick fix tool will suggest and apply to help refactor your code (including the exact opposite, "extract to local variable/field/constant", which can be invaluable).
You can write code that calls a method you haven't written yet - going to the line which now displays an error and using quick fix will offer to create a method matching the parameters inferred from your usage. Similarly so for variables.
All these small refactorings and shortcuts save a lot of time and are much more quickly picked up than you'd expect. Whenever you're about to rearrange code, experiment with quick fix to see if it suggests something useful.
There's also a nice bag of tricks directly available in the menus, like generating getters/setters, extracting interfaces and the like. Jump in and try everything out!
One thing that helped me transition from Emacs to other IDEs was the idea that IDEs are terrible editors. I scoffed at that person but I now see their point.
An editor, like Emacs or Vim, can really focus on being a good editor first and foremost.
An IDE, like Visual Studio or Eclipse, really focuses on being a good project management tool with a built in way to modify files.
I find that keeping the above in mind (and keeping Emacs handy) helps me to not get frustrated when the IDE du jour is not meeting my needs.
If you've been using emacs/vi for years (although you listed both, so it seems like you may not be adapted fully to one of them), using said editor will probably be faster for you than an IDE. The level of mind-meld a competant emacs/vi user can achieve with a customized setup and years of muscle memory is astounding.
Some free ones:
XCode on the Mac
Eclipse
Lazarus (Open Source clone of Delphi)
Visual Studio Express
Editions
Try making a couple of test applications just to get your feet wet. At first, it will probably feel more cumbersome. The benefits of IDEs don't come until you begin having a good understanding of them and their various capabilities. Once you know where everything is and start to understand the key commands, life gets easier, MUCH easier.
I think you'll find IDE's invaluable once you get into them. The code complete and navigation features, integrated running/debugging, and all the other little benefits really add up.
Some suggestions for starting out and easing transition:
- start by going through a tutorial or demonstration included with the IDE documentation to get familar with where things are in the GUI.
- look at different kinds of sample projects (usually included with the IDE or as a separate download) for different types of areas you may be coding (web applications, desktop applications, etc) to see how they are laid out and structured in the IDE.
- once comfortable, create your own project from existing code that you know well, ideally not something overly complex, and get it all compiling/working.
- explore the power! Debug your code, use refactorings, etc. The right click menu is your friend until you learn the keyboard shortcuts just to see all the things you can do. Right click different areas of your code to see what is possible and learn (or re-map) the keyboard shortcuts.
Read the doc...
And see what shortcuts/keybindings equivalents are with your familiar ones. Learn the new ones...
Old question, but let me suggest that in some circumstances, something like Notepad++ might be appropriate for the OP's situation which may be encountered by others. Especially if you are looking for something lightweight, Notepad++ can be part of a developer's arsenal of tools. Eclipse, Visual Studio and others are resource hogs with all their automagic going on and if you are looking to whip out something pretty quick with a whole bunch of keyboard shortcuts and the like or if you are interested in viewing someone else's source, this can be quite useful. Oh yeah, and it is free too.