News for hackers. Stuff that matters.
Re:Ask HN: Is there a better way to document complex softwar... by jonathanlydall on Sunday November 25, 2018 @12:15PM (#18527710)
Full disclosure: I am one of the developers of a product which does the below, also known as model driven architecture.

For about 5 years now, the teams I have been on have found great success in the use of DDD. Towards this we have used a tool which not only allows us to visually model the domain using UML, but also performs what we call “code management” (smarter code-gen which doesn’t get in your way, or produce ugly code) which turns the UML into code for our ORM of choice.

All members of the team are required to use the tool and UML to create new domain entities which then automatically become (beautifully formatted) code.

The enormous advantage of this approach is that the documentation (in the form of UML in this case), never goes out of date and lives with the code, it’s literally checked in to our Git repo in an SCM friendly format next to the normal code.

We are always able to talk around these visual models when planning a new feature or strategising a technical solution for a requirement.

An architect can at any time reason about the domain without having to first build up a mental model of it from code.

When juniors ask questions of seniors, they can both talk around the UML so that they quickly get clarity on the best way forward.

I would never go back to building business software any other way.

Re:Ask HN: Is there a better way to document complex softwar... by taeric on Sunday November 25, 2018 @12:38PM (#18527815)
If the code is generated from the diagrams, why check the code in at all? Feels akin to checking in the bytecode with your the java that generated it.
Re:Ask HN: Is there a better way to document complex softwar... by rocqua on Sunday November 25, 2018 @02:41PM (#18528557)
I can envision two reasons. The first is that, in truth, the code generated from the UML, isn't good enough and people still actually work on the output.

The second guess is that humans occasionally rewrite the code for optimization. It might then be easier to source controll the code rather than patches.

Re:Ask HN: Is there a better way to document complex softwar... by taeric on Monday November 26, 2018 @06:03AM (#18532467)
Neither of those seem like compelling reasons, though. If the code isn't good enough, you are better incentivizing the team to improve the tool's generated code, than you are increasing the drift between what the tool generates and what is used.

Optimization can almost make sense, but maintaining a patch process is almost certainly the superior way to go. If only because it supports staying current on the generated code.

Re:Ask HN: Is there a better way to document complex softwar... by derangedHorse on Sunday November 25, 2018 @06:13PM (#18529713)
There's also the reason of not wanting to generate all the code every single time someone new retrieves the repo or needs to revert back to a previous commit.
Re:Ask HN: Is there a better way to document complex softwar... by taeric on Monday November 26, 2018 @06:01AM (#18532458)
This reason doesn't make sense. Again, do you checkin the bytecode of your java? I'd expect you, instead, to recompile the java every time you do a build.

Now, I would expect you to have an artifact repository. To that end, you would be able to easily get the generated sources. But, they would decidedly not be in the source repository.

Re:Ask HN: Is there a better way to document complex softwar... by jonathanlydall on Monday November 26, 2018 @06:28AM (#18532561)
I don't feel the bytecode comparison makes sense, because the generated code is human readable, bytecode is (to almost all intents and purposes) not.

We feel that code generation is something one does explicitly while modelling, not something done every time you build.

Re:Ask HN: Is there a better way to document complex softwar... by jonathanlydall on Monday November 26, 2018 @06:23AM (#18532541)
Completely our thinking too. Code generation should not be a build or run time dependency.

Our tool also allows developers to review proposed code changes before choosing to commit them to disk.

Code generation is something you choose to do explicitly as you model.

Re:Ask HN: Is there a better way to document complex softwar... by jonathanlydall on Monday November 26, 2018 @06:09AM (#18532491)
The main reason is that our "code management" (essentially code weaving) system allows coders to painlessly mix their own custom code in the same file as generated code.

This is very useful for cases where you want to model signatures of methods in our tool, but then leave it to the developer to implement the method which performs the business code. If you want to change the signature of the method, for example adding a parameter, then our code generation will add it in without messing up your custom code.

Our own templates generate code which is as beautiful looking and readable as code written by the best developers, and we encourage template writers to do the same. This makes working with the code in your IDE and reading it as much of a pleasure as any other well written code, having it in your SCM also gives you a history of how the code has changed over time.

Finally, use of the tool is optional, if you hand the the repository over to another team, or as a contracter you deliver it to a client, they don't need the tool, and just get code which looks as if it was written by a good developer.

Re:Ask HN: Is there a better way to document complex softwar... by taeric on Monday November 26, 2018 @10:10AM (#18533805)
This sounds like a large part of the reason is you deliver the code to others, but don't want to deliver the tool you used to make the code. This makes sense to me.

For the other cases you gave, that sounds like what Interfaces were made for. :) Granted, I think we are in a world where tooling not necessarily requiring language constructs is a better place.

Regardless, if you are seeing such success, I would be greatly interested in seeing you open up that tool.

Re:Ask HN: Is there a better way to document complex softwar... by jonathanlydall on Monday November 26, 2018 @12:10PM (#18534844)
Here a recording of one of our guys on a webcast and it also shows the tool in action: https://www.youtube.com/watch?v=vA3L8_DaECQ

"No lock in" is an important aspect for us. We know of some other big players with "RAD" type tools which "generate" code, but unless one continues using their tool, the code they're left with is effectively unusable. Their business models are also often around runtime licensing.

As devs, building a tool for other devs, we want our tool to continue to be used because people clearly find the value in it, not because they feel locked in.

Re:Ask HN: Is there a better way to document complex softwar... by vruiz on Sunday November 25, 2018 @06:09PM (#18529693)
Speaking as someone who checks in other kinds of generated code. The tool, like any software, can have bugs/changes in behavior across versions. You don't want to introduce the chance of that happening without being audited in version control if you can easily avoid it.
Re:Ask HN: Is there a better way to document complex softwar... by taeric on Monday November 26, 2018 @05:59AM (#18532453)
The tool should be referenced as a versioned dependency at build time. When it gets a new release, you do a new build. Complete with new tests.

Anything you do that increases the time between the introduction of the bug and the finding of the bug will make it harder to actually fix it.

Re:Ask HN: Is there a better way to document complex softwar... by jonathanlydall on Monday November 26, 2018 @06:17AM (#18532523)
In addition to my reply above about code-weaving, rather than the all or nothing approach that some code generation techiniques suffer, our tool allows proposed changes to be reviewed before you commit with writing the generated code to your disk.

This allows developers to feel in control of what's changing in their code base during generation, rather than being worried that some custom code is going to get wiped out by code-gen without them realizing.

In a past project I was on, we had our solution build process run T4 templates to generate code, and it significantly slowed down the build process.

We feel code generation is something you explicitly do when you're "modelling", it's not something that's necessary to create a build nor should it create run-time dependency.

Re:Ask HN: Is there a better way to document complex softwar... by taeric on Monday November 26, 2018 @12:51PM (#18535276)
That attitude is ridiculously commendable, major kudos.

My fear is typically around having "mixed edited" code. That is, code that is edited by hand and generated. I greatly prefer being able to know that the generated stuff is extended by language mechanisms and I will never really have even the ability to edit something that the generator will do. I have seen bugs in generated code, but I have always pushed to fix the generator, not just fixed the generated code. (That make sense?)

And, reiterating because I feel it is important, your position is awesome. Thanks for sharing!

Re:Ask HN: Is there a better way to document complex softwar... by tachang on Sunday November 25, 2018 @12:20PM (#18527743)
What product is it?
Re:Ask HN: Is there a better way to document complex softwar... by jonathanlydall on Monday November 26, 2018 @06:29AM (#18532568)
Intent Architect[1].

Our main development focus right now is on usability for new comers and we're improving it regularly.

[1] http://intentarchitect.com/

Re:Ask HN: Is there a better way to document complex softwar... by t3hprofit on Sunday November 25, 2018 @02:26PM (#18528448)
re: full disclosure,

I appreciate your reply and that it didn't end with "So, you should use program X (the one you work on) because it's the best software". Your objective response is great.

Re:Ask HN: Is there a better way to document complex softwar... by jonathanlydall on Monday November 26, 2018 @06:43AM (#18532609)
Thank you, regardless of my interests in promoting the idea of using such a tool, we made it because we have found time and time again that always upto date visual documentation such as UML is invaluable, especially as projects get older and bigger.

Otherwise, in general we're far more interested in constructive criticism (or even just normal criticism) of our philosophy (and tool) from a place like HN, rather than trying to score a little free "advertising". When the time is right, we'll do proper promotion, and it won't be by spamming forums.

Re:Ask HN: Is there a better way to document complex softwar... by maccio92 on Sunday November 25, 2018 @01:23PM (#18528029)
What is the tool?
Re:Ask HN: Is there a better way to document complex softwar... by jonathanlydall on Monday November 26, 2018 @06:30AM (#18532570)
Intent Architect[1].

Our main development focus right now is on usability for new comers and we're improving it regularly.

[1] http://intentarchitect.com/