Self-documenting code makes its purpose clear to a reader fluent in the language without depending on comments. Comments still help with complex logic, but meaningful names and clear structure carry most of the explanation. section 2.2
Mistake #1: treating similar names as good enough. Procedures named updateStock and stockUpdate force a maintainer to inspect definitions or trace callers before even knowing which one handles an inventory bug. Ambiguous names turn a simple fix into investigation. section 2.2
Make intent visible in the code itself:
- Name database objects for their responsibility, not with vague or interchangeable verbs. section 2.2
- Name parameters and variables for the business values they hold, such as OrderQty and ProductID rather than Stock or Product. section 2.2
- Select the columns the code actually needs instead of using SELECT *, so the result and dependency are apparent. section 5.3
- Reserve SELECT * for ad hoc queries; released and maintained code should state its required columns. section 5.9
Make an inventory update readable
An order procedure becomes easier to follow when @BillingAddressID, @DeliveryAddressID, @OrderDate, @OrderQty, and @ProductID replace ambiguous names. Calling sp_updateProductStockLevel then reveals that the operation reduces stock for a specific product by the ordered quantity. section 2.2
Listing 2.6 sp_updateProductStockLevel procedure definition
CREATE PROCEDURE sp_updateProductStockLevel
@OrderQty INT, #1
@ProductID INT #1
AS
BEGIN
UPDATE tbl_products
SET StockQty = StockQty - @OrderQty
WHERE ProductID = @ProductID ;
UPDATE [DCSVR01\Inventory].InventoryDB.dbo.productStock
SET StockQty = StockQty - @OrderQty
WHERE ProductID = @ProductID ;
END
The procedure shows how descriptive parameter names make both the stock calculation and its target understandable at a glance. section 2.2
Readable code is also safer to change. SELECT * hides which columns are required, can complicate downstream type and procedure changes, and may increase network load or prevent efficient index use. Explicit intent supports maintenance as well as comprehension. section 5.3
