Discussion on: Comments Are The Only "Code Smell"

[John Peters]

I believe this is a common sentiment of lazy programming styles and in general, the common practice of most Javascript only programmers.

Code comments are the best way to expose an API, here's a classic example (shown below). As can be seen, this is an API for the package Restangular. Not a single comment which means, the programmer has to look up each method, read and understand what it does, rather than read what it does via the API.

A colossal waste of time which breeds false job security for those that "learned it" and put into a production system. Thinking my job is secure "just because only (we) know it" is a 1980's thing. Anyone using that model today should be immediately fired.

Today, it's about speed to delivery, any APIs that are poorly documented or have no API comments should be rejected in totality, and removed from current code.

So the real question is how do we use this piece of trash which has 'extraordinario mal olor'?

export declare class Restangular {
    configObj: any;
    private injector;
    private http;
    provider: {
        setBaseUrl: any;
        setDefaultHeaders: any;
        configuration: any;
        setSelfLinkAbsoluteUrl: any;
        setExtraFields: any;
        setDefaultHttpFields: any;
        setPlainByDefault: any;
        setEncodeIds: any;
        setDefaultRequestParams: any;
        requestParams: any;
        defaultHeaders: any;
        setDefaultResponseMethod: any;
        defaultResponseMethod: any;
        setMethodOverriders: any;
        setJsonp: any;
        setUrlCreator: any;
        setRestangularFields: any;
        setUseCannonicalId: any;
        addResponseInterceptor: any;
        addErrorInterceptor: any;
        setResponseInterceptor: any;
        setResponseExtractor: any;
        setErrorInterceptor: any;
        addRequestInterceptor: any;
        setRequestInterceptor: any;
        setFullRequestInterceptor: any;
        addFullRequestInterceptor: any;
        setOnBeforeElemRestangularized: any;
        setRestangularizePromiseInterceptor: any;
        setOnElemRestangularized: any;
        setParentless: any;
        setRequestSuffix: any;
        addElementTransformer: any;
        extendCollection: any;
        extendModel: any;
        setTransformOnlyServerElements: any;
        setFullResponse: any;
        $get: any;
    };
    addElementTransformer: any;
    extendCollection: any;
    extendModel: any;
    copy: any;
    configuration: any;
    service: any;
    id: any;
    route: any;
    parentResource: any;
    restangularCollection: any;
    cannonicalId: any;
    etag: any;
    selfLink: any;
    get: any;
    getList: any;
    put: any;
    post: any;
    remove: any;
    head: any;
    trace: any;
    options: any;
    patch: any;
    getRestangularUrl: any;
    getRequestedUrl: any;
    putElement: any;
    addRestangularMethod: any;
    getParentList: any;
    clone: any;
    ids: any;
    httpConfig: any;
    reqParams: any;
    one: any;
    all: any;
    several: any;
    oneUrl: any;
    allUrl: any;
    customPUT: any;
    customPATCH: any;
    customPOST: any;
    customDELETE: any;
    customGET: any;
    customGETLIST: any;
    customOperation: any;
    doPUT: any;
    doPATCH: any;
    doPOST: any;
    doDELETE: any;
    doGET: any;
    doGETLIST: any;
    fromServer: any;
    withConfig: any;
    withHttpConfig: any;
    singleOne: any;
    plain: any;
    save: any;
    restangularized: any;
    restangularizeElement: any;
    restangularizeCollection: any;
    constructor(configObj: any, injector: Injector, http: RestangularHttp);
    setDefaultConfig(): void;
    static ɵfac: ɵngcc0.ɵɵFactoryDef<Restangular, [{ optional: true; }, null, null]>;
    static ɵprov: ɵngcc0.ɵɵInjectableDef<Restangular>;
}