I'm Tom Jaeschke and you may contact me at tomjaeschke@tomjaeschke.com or (512) 419-8788.

Friday, April 2, 2010

When to Alphabetize

I am participating in a book club which is reading "Clean Code" by Robert C. Martin. Chapter 2 deals with good names and there is a line on page 20 which begins: It is very helpful if names for very similar things sort together alphabetically...



I am wrapping up a project in which I tried to keep things tidy with much alphabetization and on the other side of the experience I concluded that I really should not have done any alphabetization attempts because I found myself compromising good names in favor of marginally good names which happened to alphabetize well. Then, I read the sentence fragment mentioned above and felt conflicted.



The project is a CMS-driven web site. The simple CMS is of my own concoction. It allows administrators to create as many pages as they please for the web site and to populate the pages with content.



It has all of three persistence objects. Here is what the whole of the SQL for prepping the application looks like:





BEGIN TRANSACTION
SET QUOTED_IDENTIFIER ON
SET ARITHABORT ON
SET NUMERIC_ROUNDABORT OFF
SET CONCAT_NULL_YIELDS_NULL ON
SET ANSI_NULLS ON
SET ANSI_PADDING ON
SET ANSI_WARNINGS ON
COMMIT
BEGIN TRANSACTION
GO
CREATE TABLE dbo.Details
(
detailsId uniqueidentifier NOT NULL,
formDisplayed bit NOT NULL,
formExtraFieldDisplayed bit NOT NULL,
formExtraFieldName varchar(255) NULL,
formName varchar(255) NULL,
formRedirectsTo varchar(255) NULL,
formSendsUserAnEmail bit NOT NULL,
h1 varchar(255) NULL,
h2 varchar(255) NULL,
htmlMain text NULL,
htmlSidebar text NULL,
htmlSupplement text NULL,
metatagDescription varchar(255) NULL,
metatagKeywords varchar(255) NULL,
metatagTitle varchar(255) NULL,
pageId uniqueidentifier NOT NULL
) ON [PRIMARY]
TEXTIMAGE_ON [PRIMARY]
GO
ALTER TABLE dbo.Details ADD CONSTRAINT
PK_Details PRIMARY KEY CLUSTERED
(
detailsId
) WITH( STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO
COMMIT
BEGIN TRANSACTION
SET QUOTED_IDENTIFIER ON
SET ARITHABORT ON
SET NUMERIC_ROUNDABORT OFF
SET CONCAT_NULL_YIELDS_NULL ON
SET ANSI_NULLS ON
SET ANSI_PADDING ON
SET ANSI_WARNINGS ON
COMMIT
BEGIN TRANSACTION
GO
CREATE TABLE dbo.Page
(
folderFirst varchar(255) NOT NULL,
folderSecond varchar(255) NOT NULL,
folderThird varchar(255) NOT NULL,
linkName varchar(255) NOT NULL,
pageId uniqueidentifier NOT NULL,
suggestedPriority int NOT NULL
) ON [PRIMARY]
GO
ALTER TABLE dbo.Page ADD CONSTRAINT
PK_Page PRIMARY KEY CLUSTERED
(
pageId
) WITH( STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO
COMMIT
BEGIN TRANSACTION
SET QUOTED_IDENTIFIER ON
SET ARITHABORT ON
SET NUMERIC_ROUNDABORT OFF
SET CONCAT_NULL_YIELDS_NULL ON
SET ANSI_NULLS ON
SET ANSI_PADDING ON
SET ANSI_WARNINGS ON
COMMIT
BEGIN TRANSACTION
GO
COMMIT
select Has_Perms_By_Name(N'dbo.Page', 'Object', 'ALTER')
as ALT_Per, Has_Perms_By_Name(N'dbo.Page', 'Object', 'VIEW DEFINITION')
as View_def_Per, Has_Perms_By_Name(N'dbo.Page', 'Object', 'CONTROL') as Contr_Per BEGIN TRANSACTION
GO
ALTER TABLE dbo.Details ADD CONSTRAINT
FK_Details_Page FOREIGN KEY
(
PageId
) REFERENCES dbo.Page
(
PageId
) ON UPDATE NO ACTION
ON DELETE NO ACTION
GO
COMMIT
BEGIN TRANSACTION
SET QUOTED_IDENTIFIER ON
SET ARITHABORT ON
SET NUMERIC_ROUNDABORT OFF
SET CONCAT_NULL_YIELDS_NULL ON
SET ANSI_NULLS ON
SET ANSI_PADDING ON
SET ANSI_WARNINGS ON
COMMIT
BEGIN TRANSACTION
GO
CREATE TABLE dbo.Settings
(
emailConfirmationBody text NOT NULL,
emailConfirmationSubjectLine varchar(255) NOT NULL,
emailDetailsSubjectLine varchar(255) NOT NULL,
emailFrom varchar(255) NOT NULL,
emailTo varchar(255) NOT NULL,
globalPassword varchar(255) NOT NULL,
homeCalloutBodyI text NULL,
homeCalloutBodyII text NULL,
homeCalloutBodyIII text NULL,
homeCalloutBodyIV text NULL,
homeCalloutBodyV text NULL,
homeCalloutHeadI varchar(255) NULL,
homeCalloutHeadII varchar(255) NULL,
homeCalloutHeadIII varchar(255) NULL,
homeCalloutHeadIV varchar(255) NULL,
homeCalloutHeadV varchar(255) NULL,
homeCalloutLinkI varchar(255) NULL,
homeCalloutLinkII varchar(255) NULL,
homeCalloutLinkIII varchar(255) NULL,
homeCalloutLinkIV varchar(255) NULL,
homeCalloutLinkV varchar(255) NULL,
homeDescription varchar(255) NOT NULL,
homeKeywords varchar(255) NOT NULL,
homeTitle varchar(255) NOT NULL,
homeUrl varchar(255) NOT NULL,
locationOfSitemap varchar(255) NOT NULL,
settingsId uniqueidentifier NOT NULL
) ON [PRIMARY]
TEXTIMAGE_ON [PRIMARY]
GO
ALTER TABLE dbo.Settings ADD CONSTRAINT
PK_Settings PRIMARY KEY CLUSTERED
(
settingsId
) WITH( STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO
COMMIT
INSERT INTO Settings (emailConfirmationBody,emailConfirmationSubjectLine,emailDetailsSubjectLine,emailFrom,emailTo,globalPassword,homeCalloutBodyI,homeCalloutBodyII,homeCalloutBodyIII,homeCalloutBodyIV,homeCalloutBodyV,homeCalloutHeadI,homeCalloutHeadII,homeCalloutHeadIII,homeCalloutHeadIV,homeCalloutHeadV,homeCalloutLinkI,homeCalloutLinkII,homeCalloutLinkIII,homeCalloutLinkIV,homeCalloutLinkV,homeDescription,homeKeywords,homeTitle,homeUrl,locationOfSitemap,settingsId) VALUES ('Thank you for your information. Someone will contact you shortly.','Thank You For Your Information','Form Completion at Web Site','info@headspring.com','tom@headspring.com','e352fab0f0796d8b74cd862d4efbe145','homeCalloutBodyI','homeCalloutBodyII','homeCalloutBodyIII','homeCalloutBodyIV','homeCalloutBodyV','homeCalloutHeadI','homeCalloutHeadII','homeCalloutHeadIII','homeCalloutHeadIV','homeCalloutHeadV','/i/','/ii/','/iii/','/iv/','/v/','This is our website.','home','Home','http://www.example.com','sitemap.xml','451d856c-9e40-47cd-a659-9d3d0137fe70')







 
My objects: Settings is a grab bag of things which did not fit into the other two objects. Page suggests an individual web page within the application. I query all of the Page records to create a menu system. Each Page has a Details child which is the heavy part of the Page that is only needed on a case by case basis and not needed or wanted when querying Page records in mass to build a menu.



Note in Details the following:




htmlMain text NULL,
htmlSidebar text NULL,
htmlSupplement text NULL,



 
Following today's book club meeting I have concluded...



What I did right: grouping htmlMain, htmlSidebar, and htmlSupplement together instead of naming these bodyCopy, sidebar, and footer



What I did wrong: naming htmlSupplement as htmlSupplement instead of htmlFooter (htmlFooter is a better, more descriptive name for htmlSupplement. I decided to call the parameter htmlSupplement out of a desire to have the html parameters listed in order of perceived importance with htmlMain being the most important content on a Page, htmlSidebar being next in star power, and htmlSupplement being a distant third. Herein I compromised a good designation in the name of alphabetization.)

No comments: