• Alien Nathan Edward
    link
    fedilink
    arrow-up
    21
    ·
    edit-2
    11 months ago

    `//Get CustomerInfo from CustomerRepository by Customer ID or else throw an CustomerNotFoundException

    public CustomerInfo getById(String customerId) {

    return customerRepository.getById(customerId).orElseThrow(new CustomerNotFoundException());
    

    }`

    This is the kind of pointless comment I see in my codebase all the time. Best I can tell, a couple of my coworkers like to plan out their code using comments, then backfill in the actual executable code. That’s fine, but they leave the comments in when they add no value.

    ` public static LocalDate parseEndDateFromString(String dateString) {

        try {
    
            String[] split = dateString.split("-");
    
            //In order to get the last day of the desired month, we go to the first day of the next month, account for rollover, then subtract one day
    
            int month = Integer.parseInt(split[0]) == 12 ? 1 : Integer.parseInt(split[0]) + 1;
    
            return LocalDate.of(Integer.parseInt(split[1]), month, 1).minusDays(1);
    
        } catch (Exception e) {
    
            throw new RuntimeException("Invalid date format - must be MM-YYYY");
    
        }
    
    }`
    

    Stuff like this, otoh, is where comments are useful. The required format is obvious from the error message, the param and return from the method signature, the only part that requires a comment is the fiddly logic of accounting for the edge case where month == 12 and the rationale behind how we determine the last day of the month. As a rule, comments are for why something is being done, if it’s not obvious, and for magic numbers. Code should tell you what code does.

    edit: can anyone spot the bug that I introduced with that parseEndDateFromString() method?