Could anybody tell me if there are any tools could help to draw Effect Sketches described in Michael Feathers' book "Working Effectively with Legacy Code"??
The purpose of Effect Sketches is to show the interactions between the fields and methods in a group of coupling classes while browsing through the code.
For more information about Effect Sketches, please refer to the following blogs:
http://www.markhneedham.com/blog/2009/11/04/reading-code-unity/
http://www.markhneedham.com/blog/2010/02/23/coding-effect-sketches-and-the-mikado-method/
Thanks!
Ben Wu
The second article actually demonstrates such a tool: graphviz. Just look at the example given and write up a dot file. Then run it through the dot command line program form graphviz and you'll end up with the graph that looks like the one in the article.
A dot file is simply a description of relationships. For more on dot file syntax read up the documentation from the graphviz site or this wikipedia entry: http://en.wikipedia.org/wiki/DOT_(graph_description_language)
Related
The publish function in MATLAB works for both scripts and functions,
while the one for Octave works only for scripts: if I enter
publish myFunc.m
Octave gave
error: publish: Only Octave script files can be published.
Am I able to publish a function in Octave? If yes, how?
You can use Octave Forge generate_html package which is meant to generate html of individual functions. It is mostly used to generate the documentation of Octave Forge packages, and its defaults reflect that, but you could add any style you want.
This package will use the same help text that the help function in Octave sees which is the first block of comments in the file that does not start by Copyright or Author. You can have it in plain text but for nicer formatting, you can use Texinfo. In that case, the first line of the help text should be -*- texinfo -*-. There is a page on the Octave wiki with tips on how to write nice help text including a short section on Texinfo syntax (the actual Texinfo manual can be a bit overwhelming).
In addition to the help text, the generate_html package also identifies %!demo blocks and generates a section with the demo code and output it generates, including figures.
The best way to see how help text and demo blocks work in Octave is to check the source (as #Andy pointed out in the comments). For example, see the source for inpolygon (scroll to the bottom to find the %!demo blocks, right before %!test and %!error). The generate_html package generates this page (note the Demonstration blocks).
This is a "multiple questions in one" question, making lots of assumptions in between, so let's address those first:
1. I'll start by the question in the comment, since that's the easiest: Matlab's publisher is not a code documentation tool. It's a "make a quick report that includes both text and code to show at your supervisor meeting or write a quick point in a blog" tool. So the link you point to is simply irrelevant in this case, since that talks about documentation for matlab code.
2. The fact that matlab's publisher also "works for functions", particularly given the first point here, should be considered to be more of a bug than a feature, or at most as a trivial undocumented extension. If you look at the matlab documentation for the publish command, you'll see it expects a filename, not a function with arguments, and the documentation only talks about scripts and makes no mention of 'function' compatibility.
3. Furthermore, even if you did want to use publisher as a "documentation tool", this is counterintuitive for functions in this format, since you need to provide arguments in order for publisher to work (which will not be shown in the actual report), you'll need a modified version that displays intermediate calculations (as opposed to your normal version which presumably does not), and the function just spews an ugly ans= blabla at the end of the report. If your end goal is documentation, it might be best to write a bespoke script for this anyway, showing proper usage and examples, like matlab does in its actual documentation.
Having said all that, yes, there is a 'cheat' you can do to include a function's code in your published report, which is that, in octave (also matlab since R2016b), functions can be defined locally. A .m file that only contains function definitions is interpreted as a function file, but if there are other non-function-declaration instructions preceding the function definitions (other than comments), then it is seen as a script. So if you publish this script, you effectively get a published report with function code in it:
%% Adding function
% This function takes an input and adds 5 to it.
%% Example inputs
In = 10;
%% The function itself
% Marvel at its beauty!
function Out = myfun(In)
%% Here is where the addition takes place.
% It is a beautiful addition
Out = In + 5;
end
%% Example use
Out = myfun(In)
(If you're not happy about having to create a 'wrapper script' manually, you can always create your own wrapper function that does this automatically).
However, both the matlab and octave publishers are limited tools by design. Like I said earlier, it's more of a "quick report to show numbers and plots to your supervisor" tool, rather than a "make nice documentation or professional reports" tool. Instead, I would invest in a nice automated latex workflow, and have a look at code formatting tools for displaying code, and simply wrap that code in a script that produces output to a file that you can then import into latex. It may sound like more work, but it's a lot more flexible and robust in the long term, particularly since the formatting commands can be very quirky as well as limited.
I am coding a readme for a repo in github, and I want to add a reference to a paper. What is the most adequate way to code in the citation? e.g. As a blockquote, as code, as simple text, etc?
Suggestions?
I agree with Horizon_Net that it depends on personal preference.
I like to have something which looks similar to LaTeX.
An example is provided below.
Note that it demonstrates a numeric citation style.
Alphabetic or reading style are possible too.
For numeric citation style, higher numbers should appear later in the text, and this can make satisfying numeric citation style cumbersome.
To avoid this problem, I typically use an alphabetic citation style.
"...the **go to** statement should be abolished..." [[1]](#1).
## References
<a id="1">[1]</a>
Dijkstra, E. W. (1968).
Go to statement considered harmful.
Communications of the ACM, 11(3), 147-148.
"...the go to statement should be abolished..." [1].
References
[1]
Dijkstra, E. W. (1968).
Go to statement considered harmful.
Communications of the ACM, 11(3), 147-148.
On GitHub flavored Markdown and most other Markdown flavors, you can actually click on [1] to jump to the reference.
Apologies for taking Dijkstra his sentence out of context.
The full sentence would make this example more difficult to read.
EDIT:
If the references all have a stable link, it is also possible to use those:
The field of natural language processing (NLP) has become mostly dominated by deep learning approaches
(Young et al., [2018](https://doi.org/10.1109/MCI.2018.2840738)).
Some are based on transformer neural networks
(e.g., Devlin et al, [2018](https://arxiv.org/abs/1810.04805)).
The field of natural language processing (NLP) has become mostly dominated by deep learning approaches
(Young et al., 2018).
Some are based on transformer neural networks
(e.g., Devlin et al, 2018).
From what I know, there is no built-in mechanism for this. This leads to more subjective opinions, depending on personal preference. I personally like to have a separate section called references. An example would look like the following
References
some reference
another reference
Update
Another way would be to use simple HTML embedded in your Markdown.
The alternative (to pure markdown) is to use the new GitHub integration from Aug. 2021:
Enhanced support for citations on GitHub
GitHub now has built-in support for CITATION.cff files.
This new feature enables academics and researchers to let people know how to correctly cite their work, especially in academic publications/materials.
Originally proposed by the research software engineering community, CITATION.cff files are plain text files with human- and machine-readable citation information.
When we detect a CITATION.cff file in a repository, we use this information to create convenient APA or BibTeX style citation links that can be referenced by others.
How this works
Under the hood, we’re using the ruby-cff RubyGem to parse the contents of the CITATION.cff file and build a citation string that is then shown in GitHub when someone browses a repository with one of those files1.
Now, that is helping others making your Github paper easily citable.
But, as documented, to "add a reference to a paper":
Citing something other than software
If you would prefer the GitHub citation information to link to another resource such as a research article, then you can use the preferred-citation override in CFF with the following types.
Resource
Type
Research article
article
Conference paper
conference-paper
Book
book
Extract
preferred-citation:
type: article
authors:
- family-names: "Lisa"
given-names: "Mona"
orcid: "https://orcid.org/0000-0000-0000-0000"
I'm trying to write a small example program in Racket's scribble/lp. The source for the project is on Github.
The problem I am experiencing is broken links in the woven html. I've provided it as a gh-page. for the project.
When outputting the document using the command 'Sribble LPexample.scrbl' I get the following warning:
2013 blog > scribble LPexample.scrbl
[Output to LPexample.html]
Warning: some cross references may be broken due to undefined tags:
(dep ((lib "2htdp/image.rkt") ellipse))
(mod-path "racket")
(dep ((lib "2htdp/image.rkt") beside/align))
(dep ((lib "2htdp/image.rkt") rectangle))
(mod-path "scribble/lp")
And the output file places red underlines under the broken links.
The file which gets scribbled is LPexample.scrbl. It's pretty simple:
#lang scribble/manual
#require[scribble/lp-include]
#title{Literate Programming Example}
// snip
#lp-include["LPexample.rkt"]
The section of the literate programming document that sources the broken links is lines 69-86:
which weaves to this:
#chunk[<blue_square>
(rectangle 100 100 "solid" "blue")]
can be composed into other functions this way:
#verbatim|{
#chunk[<blue_square>
(beside/align "bottom"
(ellipse 20 70 "solid" "lightsteelblue")
<blue_square>)]}|
which weaves out to:
#chunk[<example_body>
(beside/align "bottom"
(ellipse 20 70 "solid" "lightsteelblue")
<blue_square>)]
I've been digging through the Racket documentation, of course. But there's really no good example for even cross linking documents using straight scribble/core or scribble/manual, never mind scribble/lp.
I've also tried digging through the source for the Racket documentation, but the scribble files for the the Guide and Reference use so many custom functions and macros and dependencies that I just can't get my brain far enough around it, to dig out a simple "Oh so that's how it's done".
If you want to have the identifiers from your source code automatically hyper-linked, you likely need to do two things.
One is that you need to add for-label requires for any libraries that you want Scribble to recognize. For example, you probably want (require (for-label 2htdp/image)). See this subsection of the docs for more on that.
The other is that if you're hosting the Scribble documents online the documentation links need to point somewhere, and you need to specify where. You can do that with a command-line flag. Something like this:
scribble --html +m --redirect-main http://docs.racket-lang.org/ document.scrbl
You can use different documentation URLs. For example, you might instead link to the pre-release snapshot documentation at http://www.cs.utah.edu/plt/snapshots/current/doc/.
For more details, there is a subsection of the Scribble documentation about handling cross-references: http://www.cs.utah.edu/plt/snapshots/current/doc/scribble/running.html#%28part._xref-flags%29
I wanted to ask if there are any features (or add-ons) for Doxygen to measure the documentation coverage via command line. I already know that I can set up Doxygen to write undocumented elements as warnings into a log file, but to fully evaluate the documentation coverage from that, I'd need to write my own warning log parser. Was something like this done already or is there an even easier way I couldn't find? Is there any add-on I could check out for this?
Thank you.
I don't know anything that can give documentation coverage for doxygen, but a quick search gives 2 interesting results : https://github.com/alobbs/doxy-coverage (require xml output for doxygen) and http://jessevdk.github.io/cldoc/ (alternative for c++ projects?)
There is coverxygen which is using the same idea as alobbs/doxy-coverage (uses xml output of Doxygen) but provides more options (for example, filter by access specifier).
Disclaimer: I am contributing to that project.
Is there any diff tool for Lotus Notes which allows to compare scripts, design elements and documents?
I see this is an old question, and most of the other answers are a little outdated now, so I thought I would add some hopefully valuable information for those who should stumble upon this now.
In Domino Designer, open either the Navigator or Package Explorer (Window menu -> Show Eclipse Views). Here you can expand databases/templates to see the design elements they contain. Select two or three elements (CTRL-click). They can be in different databases or the same database. Right click on one of the elements and select Compare with -> Each other.
You can also compare two databases element by element by selecting two databases/templates, right-clicking and selecting Compare with -> Each other. You will then get the differences between the two databases listed. You will be able to see which elements differ between the two databases, and which elements exist in one database but not the other. By double-clicking on a differing element, you will open a diff tool which lets you see differences line by line, and you can easily copy changes from left to right or right to left.
There is a tool from TeamStudio called Delta: http://www.teamstudio.com/products/delta.html
If all else fails (and by "all else" I mean the often ridiculous corporate procurement system) you can always do a an export to DXL (or a Design Synopsis for code alone) and use any decent text editor with a diff function. It's not TeamStudio Delta, but it will get you where you want to go.
There is a free tool from OpenNTF which does document comparisons:
http://www.openntf.org/Projects/pmt.nsf/ProjectLookup/Compare%20Notes%20Documents
Ytria also has a product which, among other things, will compare data documents (I don't believe it compares design elements).
http://www.ytria.com/website.nsf/WebPageRequest/Solutions_scanEZ_specen
And, I believe Martin Scott (http://www.martinscott.com) has a similar product which compares documents.
DDE (Domino Designer on Eclipse) let's you compare design elements natively. Same way as the search. It's pretty efficient (faster than a DXL exportation) and it's free.
I had a discussion on my blog a little while back about this:
http://rosshawkins.net/archive/2009/12/24/notesdomino-refactoringanalysis-tools.aspx
However what I've ended up doing in the past is exporting the design to the filesystem and using standard text tools (WinMerge and SublimeText for me personally) to do what I need.
Being able to do the raw dump is something that was added with the Eclipse based designer, and isn't overly obvious, but you can read more about it here:
rosshawkins.net/archive/2010/01/20/searching-the-contents-of-notesdomino-design-elements.aspx
(link mangled as my rep is too low to post 2 links in one post yet!)
Teamstudio Delta is really nice. However it might kill you with too many details. As Ross pointed out the Domino Designer 8.5 can use the Diff tool inherited from Eclipse. You also could head over to http://www.openntf.org and look for the DXLMagic project. It can generate a report that shows differences (including code) between 2 databases (typically a template and a variation of it). It is not as complete as Delta, but shows the essentials. It's free and source is included (Disclaimer: I wrote it).
This is what I do. I run a design synopsis of the database using the Notes Designer. Dump the file to a text file. You can actually split the synopsis out to different objects like Agents, Forms, Views, etc. Then you can run UNIX/Linux/Mac Unix commands to compare the elements. By doing this operation you find out what code is active, and have a complete documented source code. You do a lot of csplit and a few sed commands.
Version 12.0.1 has such a tool as part of the server. Look for comparedbs.ntf and designsynopsis.ntf on the Domino server.