• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Tim Cooke
  • paul wheaton
  • Jeanne Boyarsky
  • Ron McLeod
Sheriffs:
  • Paul Clapham
  • Liutauras Vilda
  • Devaka Cooray
Saloon Keepers:
  • Tim Holloway
  • Roland Mueller
Bartenders:

I never make any mistakes because I can't see them.

 
Marshal
Posts: 80259
428
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
From this post from yesterday:-

Tim Holloway wrote:. . . Any beginner can spot [the mistake]. I can't because I "know" what's there and thus can't see it's not there. . . .

I have had the same problem myself. How frequent do people think it is, that we can't see our own mistake even if it is instantly obvious to somebody else? Does that phenomenon come up in the book?
 
Marshal
Posts: 5803
371
IntelliJ IDE Python TypeScript Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
That makes a lot of sense.

The problem with your own mistakes is that you're the one that made them, and given that you didn't intentionally make the mistake it follows that you are unaware that it is a mistake.

There is a slightly different flavour of "mistake" that you might categorise as a deliberate mistake. That is one dependent on some context that a newcomer might not be aware of. In those instance I am a proponent of the ADR (Architecture Decision Record), and it's here where you can explain why a particular decision was made so that the newcomer doesn't have to wonder. Without an ADR the newcomer has 2 choices, either blindly accept the current state, or change it, and either one of those decisions could be a mistake. Perhaps the context supporting the original decision has changed and doing something different is the right thing to do, or perhaps it hasn't and leaving things as they are is the right thing to do. Without understanding the motivators behind the original decision you just don't know, until you do, later.
 
Sheriff
Posts: 7001
6
Eclipse IDE Python C++ Debian Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Tim Cooke wrote:There is a slightly different flavour of "mistake" that you might categorise as a deliberate mistake



The more I think about this the more I keep seeing different types of mistakes. This makes me think of what you might call a "temporary" or "semi-deliberate" mistake.

It's easy to slip into thinking of a relatively static view of a codebase, and categorising some parts as correct and others as mistakes. But there is another view, which looks at the evolution of the code over time, where we can observe that some mistakes exist only for a particular period. The problem comes when such mistakes linger long enough to cause actual problems.

I'm sure we have all been there. In order to meet a deadline or complete a different feature, you hack or hard-code something which is not key to the task in hand. Test-Driven Development (TDD) actively encourages this approach. The danger is that this hack or hard-coded result may end up going live, particularly on projects with a frequent delivery schedule. Such mistakes are always intended to be fixed, but we can never know the future, and in some number of cases the deliberate error remains in the system for much longer than originally planned.

These kinds of mistakes count as deliberate, in that some developer implemented them with eyes open, but the inclusion in the deployed software is an accidental or unintended consequence.
 
Campbell Ritchie
Marshal
Posts: 80259
428
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Tim Cooke wrote:. . . a deliberate mistake. . . .

I occasionally introduce deliberate mistakes into posts here, or leave accidental mistakes for tthe punters to find themselves.

Without understanding the motivators behind the original decision you just don't know, until you do, later.

That is why the documentation should be readily available and regularly updated. The updates should (I think) be identifiable as updates as opposed to part of the original document. It isn't like a thesis (Frank, take notice), where you may decide things haven't gone as expected and have to change dozens of pages and overwrite the old text. Or even delete dozens of pages. In that case you would of course record the changes with Git or similar.
 
Tim Cooke
Marshal
Posts: 5803
371
IntelliJ IDE Python TypeScript Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Yes, once accepted ADR's are immutable. If you change your mind on a decision later you document that decision in a new ADR and state that it supersedes an existing ADR.
 
Saloon Keeper
Posts: 28480
210
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Tim Cooke wrote:Yes, once accepted ADR's are immutable. If you change your mind on a decision later you document that decision in a new ADR and state that it supersedes an existing ADR.

Sounds like an RFC

I haven't seen that particular approach before for software design, but in Java, I put the specs into the JavaDocs and into the Functional Specification document that generally preceded the actual coding (and is updated by it). My Functional Spec docs are an equivalent of a bound volume of ADR's, and sometimes they themselves come from exported MindMaps, if I'm doing lots of on-the-fly templating.

People don't really appreciate what JavaDocs can do. You can not only get automated documentation on individual methods, you can embed HTML directives into them, including tables and images. You can document the component abstractly in its heading doc element and document an entire subsystem in a package-info file. And you can instantly get your own private up-to-date copy by running the JavaDoc tool, which is often an IDE menu option.

The perennial issue remains, of course, maintainers often don't update the comments, but the same can be said of "immutable" external documents.
 
Tim Cooke
Marshal
Posts: 5803
371
IntelliJ IDE Python TypeScript Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
We use ADR's in a broader context. JavaDocs are good for documenting decisions you've made in your Java code, but less so on on the decision to use Java in the first place, or why we decided to run it in a container rather than an EC2 (in AWS), or why we chose AWS over GCP, or Azure, or whatever.
 
Tim Holloway
Saloon Keeper
Posts: 28480
210
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I got cued in on a document strategy that was basically stolen from Rational, filtered through Oracle, then passed down from my boss (formerly with Oracle). The standard document set is like so:

ES - Executive Summary. 1-2 pages indicating why the project is needed, what it does, costs, and basic infrastructure requirements.
FS - Functional Spec. Design and architecture of the system
IS - Implementation Spec. How the Functional Spec is to be implemented in technical detail
UG - User Manual. User's guide to the system. May be supplemented by Administrator's Guide and/or Operator's Guide

 
reply
    Bookmark Topic Watch Topic
  • New Topic