Joel on Software

Joel Spolsky

Mentioned 4

Joel Spolsky began his legendary web log, www.joelonsoftware.com, in March 2000, in order to offer insights for improving the world of programming. Spolsky based these observations on years of personal experience. The result just a handful of years later? Spolsky's technical knowledge, caustic wit, and extraordinary writing skills have earned him status as a programming guru! His blog has become renowned throughout the programming worldnow linked to more than 600 websites and translated into over 30 languages. Joel on Software covers every conceivable aspect of software programming—from the best way to write code, to the best way to design an office in which to write code! All programmers, all people who want to enhance their knowledge of programmers, and all who are trying to manage programmers will surely relate to Joel's musings. Table of Contents Choosing a Language Back to Basics The Joel Test: 12 Steps to Better Code The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets (No Excuses!) Painless Functional Specifications Part 1: Why Bother? Painless Functional Specifications Part 2: What’s a Spec? Painless Functional Specifications Part 3: But . . . How? Painless Functional Specifications Part 4: Tips Painless Software Schedules Daily Builds Are Your Friend Hard-Assed Bug Fixin’ Five Worlds Paper Prototyping Don’t Let Architecture Astronauts Scare You Fire and Motion Craftsmanship Three Wrong Ideas from Computer Science Biculturalism Get Crash Reports From Users—Automatically! The Guerilla Guide to Interviewing Incentive Pay Considered Harmful Top Five (Wrong) Reasons You Don’t Have Testers Human Task Switches Considered Harmful Things You Should Never Do, Part One The Iceberg Secret, Revealed The Law of Leaky Abstractions Lord Palmerston on Programming Measurement Rick Chapman Is In Search of Stupidity What Is the Work of Dogs in This Country? Getting Things Done When You’re Only a Grunt Two Stories Big Macs vs. The Naked Chef Nothing Is As Simple As It Seems In Defense of Not-Invented-Here Syndrome Strategy Letter I: Ben & Jerry’s vs. Amazon Strategy Letter II: Chicken-and-Egg Problems Strategy Letter III: Let Me Go Back! Strategy Letter IV: Bloatware and the 80/20 Myth Strategy Letter V: The Economics of Open Source A Week of Murphy’s Law Gone Wild How Microsoft Lost the API War Microsoft Goes Bonkers Our .NET Strategy Please Sir May I Have a Linker?

More on Amazon.com

Mentioned in questions and answers.

Is it absolutely necessary to use "arrows" to show association between an actor and a use case in a use case diagram?

I recently had to draw one for my Software Engineering assignment. But after doing a bit of research online on many articles, papers, online books and lecture notes from numerous other universities, it seemed that majority of use case diagrams regardless of how much potential they have to show some kind of "flow" or "navigability", have no arrows, while some examples have arrows.

So I consulted my friend who is a final year student and has already studied what I have told me I shouldn't have arrows between my actor and use case and even his Requirements Engineering lecturer taught students not to use arrows. So I made a conscious decision not to use arrows and used solid lines instead to show my use case associations.

Here is my diagram- click

However, when I received the marks for my assignment, I was astonished to find out that I was given a zero for not using arrows. Even if it was mandatory to use them, there is an abundance of evidence that a solid line can be used for bi-directional association. So shouldn't I receive at least some marks for it?

Obviously I asked for an explanation from my lecturer who I will see next week to discuss this point, but if she tells me I should have used arrows, what argument can I make against it? I would be grateful if someone can kindly give me good advice with appropriate references to some professional sources.

Thank you very much for reading and I hope to read your response soon.


EDIT

Thank you guys. I really appreciate the answers you have given me. This whole confusion started because the only notation the lecturer provided was a single,very simple example of library use case diagram in one of the lecture notes, which had arrows. But it was not made very clear that it was the definitive notation. Another reason I didn't think it was mandatory is because when it came to explaining notations for drawing a data-flow diagram, she made it abundantly clear to using her specific notations, but it is not that uncommon for DFD's to have different notations in different sources, whereas I could find very little evidence to make the use of arrows in use-case diagrams necessary.

That said, even before going through without arrows, I remember asking one of the tutors (not the lecturer) during a tutorial session what's the difference between having and arrowed line and a solid line and he said there is none and I could use both. Obviously for that I only have my word and from what you guys have said, I doubt anyone in an academic position would admit to telling something that could put them in a defensive position. My mistake was not speaking to the lecturer directly, but in hindsight I obviously would have done it.

Anyway, I will speak to her regarding all this information and request her to take this "honest mistake" into consideration. It's also not just the use case diagram but a couple of other questions that I lost an unusual amount of marks on, especially when my answers are almost identical to the model answers she provided. I also know a lot of other students who have requested their assignments get remarked.

Hopefully she will be kind and use good judgement to improve my mark. I will post back here when I find out.

Thanks again for your help and please post any other info/suggestions you may have. :)


EDIT 2

Sorry guys, I have another question.

Here is the scenario that was given in the assignment to draw the use case diagram.

CONTHETICKET is a ticket agency dealing in Concert and Theatre tickets. Concert and theatre venues provide CONTHETICKET with a constant stream of information on forthcoming events, which is then used by the Manager to compile a fixture list for use by the sales staff in responding to customer calls. The manager selects some events for which CONTHETICKET will purchase a number of tickets in advance, thereby benefiting from discounts negotiated with the venues.

He personally sends the orders for the tickets together with the agreed payments to the venues, and once tickets are received, he files them in the ticket File.

When customers ring the sales team, their ticket requests are checked against the ticket file. If pre-purchased tickets are available they are put in an envelope marked with the customer's name and address, and filed in a provisional orders file. If not, the sales team fills out a ticket request form and put it in a tray for collection by the post clerk.

The payments section checks the provisional orders file daily. They send an invoice to the customer and await payment. A copy of the invoice is kept on file. When a payment is received, the payments section match the payment with the appropriate invoice, and if satisfied place another copy of the invoice in a despatch file with instructions to despatch the tickets.

The post clerks checks the despatch file each day and retrieves the appropriate tickets from the provisional orders file and sends them to the appropriate customers.

As you can see from my diagram I have an "Concert & Theatre Venues" as an actor.

From The Elements of UML 2.0 Style, Scott W. Ambler:

"An actor is a person, organization, or external system that plays a role in one or more interactions with your system (actors are typically drawn as stick figures on UML Use Case diagrams)."

However, on my marked assignment, the lecturer commented that it should not be an actor. Can you please tell me whether or not you think it should be an actor and why.

My rationale behind it is CT&V are supplying event information which is then used by the manager to order/file tickets, also supplied by CT&V.

Thank you very much.

Your instructor, giving you a 0 for not using arrows in your use diagram, is an example of him teaching you the wrong things about Software Engineering.

Creating a spec for a software product, out in the real world, is not getting your arrows right.

It's about creating a living document that forms the foundation behind your project. The key aspects of any spec is that:

  1. The project team actually reads it
  2. The document is effective at capturing your intent

The idea that what you should be learning is how to draw in your arrows the right way is ridiculous. If you get a chance, you should read this article:

http://www.joelonsoftware.com/articles/fog0000000024.html

It captures my sentiments excellently.

It sounds like to get through your class you need to pretend to be interested in UML arrows. My advice to you is:

  1. Do what is necessary to get a good grade in the class
  2. The second you finish the final exam PLEASE forget everything you learned in that class, because it's only going to harm you.
  3. Pickup up a copy of this book, and read it. The whole thing.

Will facebook allow you to reference a unrelated domain in the open graph meta tags?

For instance lets say the user, Bill, navigated to the following page on my site:

http://BillsEmployer.MySite.Com/ProductSuggestions

within the section in the html I have the following element

<meta property="og:url" 
      content="http://rads.stackoverflow.com/amzn/click/1590593898" /> 

Bear in mind, I'm only using Amazon as an example. My real implementation will not reference AMAZON. But it will reference a site that I don't actually have any control over.

If Facebook won't let me use a 3rd party site as a canonical URL, would I be able to reference a different domain that I do control? In other words could I point

http://CompanyA.MySite.com, http://CompanyB.MySite.Com, http://CompanyC.MySite.com all to a canonical URL at http://generic.MySite.com?

I work for a small software company with less than 10 programmers. Our software is installed in dozens of places across the world. Our code base is huge, due mostly to poor design and massive amounts of duplication of code (IMO). We have roughly 30 different projects, each with a total of about 600 KLOC with about 200 KLOC of that being our own homegrown code. When I got there in 2006, this code wasn't even under revision control. I've managed to convince powers that its important, and we now use a code control system (cs-rcs, not my choice but its better than nothin), and a bug tracking system. The huge missing piece is the total and complete lack of QA in the process. Our release process is non existant on paper, and in practice it consists of "hit ctrl-F9, copy binary to client, declare problem fixed."

Can anyone point me to some official papers or PHB-language documents or articles that can explain the blatant lunacy in this process? I'm sure the boss could hire some consultant to tell him this, and then he might believe it. But I'm just a lowly maintainer with a Software Engineering BS degree. And my ethnicity doesn't help me either. What's the best ammunition to use in this case?

Tautologically, the only way to convince them is put them in front of something that is convincing. That thing could be drawn from a list such as:

  • The foretold expensive disaster that prompts adoption of the previously-presented solution
  • The unforetold disaster with a ready-made never-again solution
  • A brilliantly persuasive foretelling of a disaster
  • A brilliantly persuasive appeal to greed (saving the opportunity cost of a foretold disaster)

Or something else. In all these cases, someone is going to have to make the case at some point for the QA solution you propose, and that someone, from the looks of it, is going to have to be you. So I'd start learning about being persuasive.

How to Win Friends and Influence People should cost you a few bucks at most. Getting To Yes is also cheap.

How did you get agreement to source control? Can you keep chipping away, improving the process a small increment at a time?

Try Googling "change your organization", there looked to be some promising links.

And ultimately, remember that (as a wise man once said) if you can't change your organization then you should change your organization. There really is always an alternative.

Refer Joel's book

I have had a few development managers who don't seem to understand or appreciate the difficulties of software design and implementation.

Such managers believe that processes and methodologies completely solve the problem and I have a tough time explaining to them that it is not so and that you cannot read a book on the latest process fad and hope to get results by applying them as is.

The latest frustration I have is to convince my manager to (a) Give me requirements not piece-meal but a larger set as far as possible. (b) Give my team lead time to think about how to design, thrash out a few alternatives, work out an implementation sketch, to plan out the tasks etc.

The frustrations are compounded because of Agile methodology and the interpretation of it that says not to do up-front design (as against BIG up-front design in Waterfall), product owner can change requirements at any time and so son.

So far I haven't had much success and have to put up with the resulting frustrations. Can you give me some arguments that can convince such managers?

EDIT-1: Retrospectives are done, though not always at the end of every sprint, and the problems are brought up. But as I mentioned, my manager doesn't appreciate the need for design lead time and the frustrations with piece-meal requirements.

EDIT-2 I don't have a problem with changing requirements. I understand that it will be so, but imagine this: You want a small feature to begin with and then you keep adding more around it. After a few iterations, the design cannot handle it anymore and a redesign (not refactoring) is required. This could have been solved better with an upfront design in the first place, had the related features been investigated together. Its not BDUF, its the natural way of doing it (what I call software engineering common sense).

My manager doesn't understand why I ask for time to redesign (a few times I just call it refactoring so that it fits the Agile way of doing it, but it really is redesign) and not developing and demoing new features.

Buy your manager this book. That's what I did, and it worked great :)

I'm confused by the terms. When I make an PHP application that

1) can be called with an URL or HTTPRequest, with parameters (i.e. country id), and returns data (XML or anything else)

2) can be called in order to store data (i.e. user wants to store all his contacts online on the server)

Is that still ok to call this thing a "Web Service", and the whole activity ranging from fetching data and submitting data a "Web Service Call"?

Yes, that's normal enough terminology. A service is a process that "does something." And that "something" can be anything that either takes input, provides output, or both.

  • returnLibraryBook("Joel on Software") - takes input, modifies database
  • getCheckedOutBooks() - provides output; a list of books currently checked out
  • locateNearestStarbucks("90210") - takes input, provides output

In essence Web Services amount to remote method calls across the HTTP protocol.